frankenreview 9.5.0
A multi-layered, agentic, context-aware, zero-cost code reviewer
License: MIT
Requires Python: >=3.8
Keywords: code-review, ai, automation, gemini, llm, developer-tools

# Frankenreview v9.5 "The Agentic Agility Update"

<p align="center">
  <img src="https://img.shields.io/badge/version-9.5.0-blue.svg" alt="Version">
  <img src="https://img.shields.io/badge/python-3.8+-green.svg" alt="Python">
  <img src="https://img.shields.io/badge/cost-$0.00-success.svg" alt="Cost">
  <img src="https://img.shields.io/badge/mode-autonomous-purple.svg" alt="Autonomous Mode">
  <img src="https://img.shields.io/badge/status-production--ready-brightgreen.svg" alt="Status">
</p>

> A **multi-layered, agentic, context-aware, zero-cost code reviewer and research agent** with native local intelligence.

**Status:** High-Precision Continuous Execution | **Intelligence:** Cloud (Gemini) + Local (MLX/Llama.cpp) | **Cost:** $0.00

> [!CAUTION]
> **AI Studio Data Usage Disclaimer**
> 
> Google AI Studio may use code submitted for model training purposes.
> **Do NOT submit proprietary, confidential, or sensitive code.**
> a paid plan where data usage terms may differ.
>
> [!NOTE]
> **File Upload Robustness**: v9.0 automatically converts XML dumps to `.txt` during upload to verify compatibility with AI Studio's strict file filtering.

## What's New in v9.5 -> "The Agentic Agility Update" (Jan 2026)

- **Local Cortex Interaction**: Native repo-aware chat using `mlx-lm` (Metal) or `llama-cpp-python`.
- **Agentic File Browsing**: The local model can now autonomously read repository files to answer questions.
- **Dockerized Review Sandbox**: Secure, isolated review environments for untrusted code.
- **Self-Healing Diagnostics**: `--self-check` for automatic syntax, import, and configuration validation.
- **Stateful Conversation**: Memory-enabled interactive REPL via `frankenreview --chat`.

## What's New in v9.0 -> "The Deep Scan Update"

- **Deep Scan Mode**: Recursively critique the codebase with `--deep-scan`.
- **Planner Validation**: Verify implementation plans with `--planner`.
- **Multi-Head Architecture**: Run parallel agents with custom ports (`--port`).

## What's New in v7.1 -> "The Autonomy Update"

- **Project-Specific Prompts**: Create custom prompts per-project (`--create-prompt`) stored in `.frankenreview/prompts/`.
- **Explicit Doctrine**: Built-in access to the "High-Precision Continuous Execution" doctrine (`--rigour`) and workflow (`--workflow`).
- **Agent Autonomy**: Full CLI machine-readability and brute-force verified robustness.
- **Research Hygiene**: Intelligent input logging to `.frankenreview/research_input.md`.

## What's New in v6.0 (Jan 2026) -> "The Research Build"

- **Research Mode**: New `--research` command for agentic deep research via Gemini Flash functionality.
- **VS Code Extension v2.0**: Status bar integration, file watcher, and notifications for GitHub Copilot Chat.
- **CLI Chrome Management**: Global commands `--start-chrome` and `--stop-chrome` for browser control.
- **Centralized Output Folder**: All outputs go to `.frankenreview/` (auto-gitignored) for cleaner projects.
- **Automatic Dump Cleanup**: Automatically deletes stale code snapshots (keeps last hour only).
- **Thinking Mode Support**: Full support for **Gemini Flash Thinking**.
- **Robust File Upload**: Directly uploads codebase snapshots as files (`.xml`).
- **Silent Operation**: Runs in a minimized window—no focus stealing or popups.

## Core Features

- **Research Agent** - Run deep research queries through Gemini Flash with structured output.
- **Centralized Outputs** - All artifacts in `.frankenreview/` (dumps, review.md, state) - auto-gitignored.
- **Local Cortex** - Integrated local LLM for instant, repository-aware interactive chat.
- **Docker Sandboxing** - Secure execution of one-shot reviews in isolated containers.
- **Intelligent Change Detection** - Distinguishes trivial (formatting) from critical (logic) changes.
- **Automatic Cleanup** - Prevents stale cache issues by deleting old snapshots.
- **Dual-Brain Analysis** - Cloud (Gemini) for complex reasoning, Local Cortex for rapid repository reflex.
- **Project Memory** - Remembers constraints and review history per project.
- **Free Cloud AI** - Uses Gemini via browser automation (no API costs!).
- **VS Code Integration** - Status bar and notifications for GitHub Copilot Chat.

## Architecture

```
+-------------------------------------------------------------+
|           LAYER 1: WATCHER (File Monitor)                   |
+--------------------+----------------------------------------+
                     | 10s silence
                     v
+-------------------------------------------------------------+
|           LAYER 2: GATEKEEPER (LLM or Heuristics)           |
+---------+----------------------------------+----------------+
     TRIVIAL                             CRITICAL
          v                                  v
+----------------------+          +--------------------------+
|   LAYER 3: JANITOR   |          |   LAYER 4: SQUEEZER      |
+----------------------+          +------------+-------------+
                                               v
                                  +--------------------------+
                                  |   LAYER 5: MEMORY        |
                                  +------------+-------------+
                                               v
                                  +--------------------------+
                                  |  LAYER 6: CLOUD BRAIN    |
                                  +--------------------------+
```

## Architecture Resilience (Zero-Eager-Import)

Frankenreview uses a **Strictly Optional Dependency** model to ensure 100% startup reliability across diverse hardware (Intel/Silicon/Linux).
- **Zero-Eager-Import**: The package root (`__init__.py`) is neutralized. Importing `frankenreview` is a zero-cost operation.
- **Lazy Logic**: Heavy libraries (like `llama-cpp` or `mlx-lm`) are only loaded locally within the methods that require them (e.g., `--chat` or `--self-fix`).
- **Safe Probing**: Backend availability is checked via metadata (`find_spec`) without importing the actual library, preventing `OSError` crashes on architecture mismatches.

## Quick Start

### 1. Install

```bash
# Clone the repository
git clone https://github.com/SNiPERxDD/Frankenreview.git
cd Frankenreview

# Install as package  
pip install -e .
playwright install chromium
```

### 2. Configure

Edit `config.yaml`:

```yaml
project_root: "/path/to/your/project"  # Change this!
chat_url: "https://aistudio.google.com/prompts/new_chat?model=gemini-flash-latest"
thinking_mode: true                     # Enable for Gemini Flash Thinking models
delete_after_review: true               # Auto-delete chat after review (Recommended)
```

### 3. Launch Chrome

```bash
# NEW in v6.0: Global Chrome Management
frankenreview --start-chrome
```

1. Chrome will open.
2. Log into [Google AI Studio](https://aistudio.google.com).
3. **Minimize** the window (Frankenreview runs silently in the background).

### 4. Run

**Mode A: One-Shot Review (Best for CI/Agents)**
Review the current state of the codebase immediately.
```bash
frankenreview -r
```

**Mode B: Watch Mode (Daemon)**
Watch for file changes and review automatically.
```bash
frankenreview -w
```

**Mode C: Project-Specific Prompt (NEW v7.1!)**
Review using a custom prompt tailored to this project.
```bash
# Create prompt
frankenreview --create-prompt architecture_audit

# Run review
frankenreview -r --prompt architecture_audit
```

**Mode D: Research Mode (NEW!)**
Run agentic deep research on any topic.
```bash
# Create a prompt file with your research question
echo "Research best practices for implementing WebSocket authentication" > topic.md

# Run research
frankenreview --research --prompt topic.md --output analysis.md
```

## Agent Integration (The Protocol)

For AI Agents controlling Frankenreview, follow this **Strict Protocol**:

1.  **READ DOCTRINE**: `frankenreview --rigour`
2.  **READ PROCESS**: `frankenreview --workflow`
3.  **PRUNE GARBAGE**: `frankenreview --token-eaters`
4.  **EXECUTE REVIEW**: `frankenreview -r`
5.  **MAINTAIN DOCS**:
    *   Update `CHANGELOG-MINI.md` for *every* task.
    *   Prune `CHANGELOG.md` if >500 lines to prevent context hallucination.

## Background Execution (Production Tips)

To run the watch mode in the background, immune to terminal interrupts:

```bash
nohup frankenreview -w > frankenreview.log 2>&1 &
```

Stop it with:
```bash
frankenreview --stop-chrome
```

## Prune Configuration (AI Agent Control)

AI agents can control what gets excluded from code reviews:

```bash
# View current prune configuration
frankenreview --prune-list

# Add/remove directories, files, or extensions
frankenreview --prune-add-dir "my_folder"
frankenreview --prune-remove-dir "tests"
frankenreview --prune-add-file ".env.local"
frankenreview --prune-add-ext ".csv"
```

Changes persist to `config.yaml` automatically.

## Token Eaters (Pre-Review Analysis)

Analyze repo to identify heavy content before running a review:

```bash
frankenreview --token-eaters
```

Example output:
```
TOP 10 FILES (by token count):
  1   26,994   18.2%   src/frankenreview/browser_client.py
  2   15,294   10.3%   src/frankenreview/cli.py
...
TIP: Use --prune-add-dir or --prune-add-file to exclude heavy items.
```

## Chrome Performance Stats

Monitor Chrome resource usage during reviews:

```bash
frankenreview --chrome-stats
```

Shows CPU, memory (RSS), JS heap, DOM nodes, and GPU status.

## 8. Multi-Head Architecture (v8.0)
Frankenreview supports simultaneous multi-agent operations.
- **Run Multiple Agents**:
  ```bash
  # Instance 1: Default
  frankenreview --start-chrome
  frankenreview -r
  
  # Instance 2: Custom Port & Profile
  frankenreview --start-chrome --port 9223 --profile dev
  frankenreview -r --port 9223
  ```
- **Context Upload**:
  ```bash
  frankenreview -r --attach logs/error.log --attach docs/spec.md
  ```

## 9. Deep Scan & Planner (v9.0)
Advanced autonomy features for critical analysis.

### Deep Scan (`--deep-scan`)
Recursive, self-correcting review loop.
```bash
frankenreview --deep-scan --cycles 3
```
- **Cycle 1**: Standard review.
- **Cycle 2+**: AI reviews the codebase *and* its previous findings, looking EXCLUSIVELY for deeper flaws missed in the first pass.

### Planner Critique (`--planner`)
Before writing code, validate your plan.
```bash
# 1. Create plan.md
# 2. Run Planner
frankenreview --planner
```
The AI critiques `plan.md` against the repo, spotting hallucinated dependencies, logic gaps, or regression risks.

## 10. Rigour & Hygiene
- **Data Hygiene**: `frankenreview --dump --prune-changelogs` (Truncates history to prevent context overflow).
- **Anti-Hallucination**: Enforced by STRICT prompts in `audit.md` and `rigour.md`.


## Project Structure

```
frankenreview/
├── src/frankenreview/      # Main package
│   ├── cli.py              # Entry point & Argument Parsing
│   ├── browser_client.py   # Playwright Automation (The "Ghost")
│   ├── daemon.py           # File watcher
│   ├── governor.py         # Change analysis logic
│   ├── repo_dumper.py      # Context packer
│   └── output.py           # Production UI helper
├── scripts/                # Utility scripts (Python)
├── dumps/                  # Debug snapshots & logs
├── tests/                  # Test suite
└── config.yaml             # Configuration
```

## Troubleshooting

| Issue | Solution |
|-------|----------|
| Chrome not found | Run `python scripts/start_chrome.py`. Ensure port 9222 is free. |
| "Unsupported file" | We now auto-convert to `.txt` for upload. Ensure `cli.py` is updated. |
| Extraction fails | The system now handles "Thinking" blocks. Check `dumps/last_response_dump.html`. |
| Browser steals focus | Ensure `silent_mode: true` in config. We minimize the window on start. |
| `llama_cpp` Crash | **Resolved in v9.5.5**: We now use "Zero-Eager-Import" to make the Cortex strictly optional. |

## Documentation

- [Selector Guide](docs/SELECTOR_DISCOVERY_GUIDE.md) - How we reverse-engineered AI Studio
- [Feature Catalog](docs/FR_FEATURE_CATALOG.md) - Complete list of v5.0 capabilities
- [Architecture](docs/ARCHITECTURE.md) - Deep dive into the system

## License

MIT License - See [LICENSE](LICENSE) for details.

---

<p align="center">
  <b>Built with Frankenreview by the Frankenreview Team</b>
</p>