frankenreview 9.5.0

A multi-layered, agentic, context-aware, zero-cost code reviewer

Frankenreview v9.5 "The Agentic Agility Update"

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

# 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:

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

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

1. Chrome will open.
2. Log into Google AI Studio.
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.

frankenreview -r

Mode B: Watch Mode (Daemon) Watch for file changes and review automatically.

frankenreview -w

Mode C: Project-Specific Prompt (NEW v7.1!) Review using a custom prompt tailored to this project.

# 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.

# 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:

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

Stop it with:

frankenreview --stop-chrome

Prune Configuration (AI Agent Control)

AI agents can control what gets excluded from code reviews:

# 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:

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:

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:

  # 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:

  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.

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.

# 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 - How we reverse-engineered AI Studio
• Feature Catalog - Complete list of v5.0 capabilities
• Architecture - Deep dive into the system

License

MIT License - See LICENSE for details.

---

Built with Frankenreview by the Frankenreview Team