codereaper 0.1.0

AI-driven JavaScript dead code elimination via browser agent + V8 coverage

CodeReaper

AI-driven JavaScript dead code elimination for websites and Chrome extensions.

CodeReaper scans a target URL or unpacked Chrome extension, autonomously explores the UI via the Index browser agent, collects V8 precise coverage data, and produces verified unified diffs that safely remove dead code.

Install

pip / pipx (recommended)

pip install codereaper
playwright install chromium

Or with zero-install via pipx:

pipx run codereaper          # starts MCP server directly

npm / npx

npx codereaper               # auto-detects uvx/pipx/python

From source

git clone https://github.com/your-org/codereaper.git
cd codereaper
pip install -e ".[all]"
playwright install chromium

Configure

Create a .env file in the project root (or set environment variables):

# LLM for Index browser agent
CODEREAPER_INDEX_LLM_PROVIDER=gemini
CODEREAPER_INDEX_LLM_MODEL=gemini-2.5-pro-preview-05-06
GOOGLE_API_KEY=your-key-here

# Or use OpenAI / Anthropic
# CODEREAPER_INDEX_LLM_PROVIDER=openai
# CODEREAPER_INDEX_LLM_MODEL=gpt-4o
# OPENAI_API_KEY=your-key-here

# Storage (optional, defaults shown)
CODEREAPER_DATA_DIR=./data
CODEREAPER_DB_PATH=./data/codereaper.db

Cursor MCP Integration

CodeReaper runs as an MCP (Model Context Protocol) server that Cursor invokes to scan websites, find dead code, and suggest what to delete.

Add to Cursor

Add one of these to your .cursor/mcp.json:

If installed via pip:

{
  "mcpServers": {
    "codereaper": {
      "command": "codereaper"
    }
  }
}

If using pipx (zero-install):

{
  "mcpServers": {
    "codereaper": {
      "command": "pipx",
      "args": ["run", "codereaper"]
    }
  }
}

If using npx (zero-install):

{
  "mcpServers": {
    "codereaper": {
      "command": "npx",
      "args": ["-y", "codereaper"]
    }
  }
}

From source (development):

{
  "mcpServers": {
    "codereaper": {
      "command": "python3",
      "args": ["-m", "codereaper.mcp"],
      "cwd": "/absolute/path/to/codereaper"
    }
  }
}

Restart Cursor after editing mcp.json.

Usage in Cursor

Ask the assistant to find dead code:

"Find dead JavaScript code on http://localhost:3000"

The assistant calls find_dead_code which:

1. Launches a browser with an AI agent that explores the site
2. Collects V8 code coverage showing which functions executed
3. Returns a report of every function with zero executions

Provide a local source directory so the report maps URLs to local files:

"Find dead code on http://localhost:3000, source is in ./test_site"

MCP Tools

Tool	Description
find_dead_code	Full pipeline: scan + analyze. Returns dead-code report with file paths, line numbers, risk scores, and removal recommendations.
scan_website	Scan only (no analysis). Returns scan_id for later use.
analyze_dead_code	Analyze a completed scan. Takes scan_id.
generate_patches	Generate unified diffs to remove dead code (conservative / balanced / aggressive).
get_patch_diff	Retrieve the combined diff for a patch.
apply_patch	Apply a patch to source files (stores snapshots for rollback).
verify_patch	Re-run the browser agent to check for regressions after patching.
rollback_patch	Restore original files from pre-patch snapshots.
list_scans	List recent scans.
get_scan_status	Get detailed status of a scan.

REST API

CodeReaper also exposes a REST API via FastAPI for programmatic access.

Start the API server

codereaper-api                                          # console script
python -m codereaper.api                                # module
uvicorn codereaper.api.app:app --reload --port 8000     # uvicorn directly

API docs at http://localhost:8000/docs.

Endpoints

Method	Endpoint	Purpose
POST	/api/v1/scans	Start scan + exploration
GET	/api/v1/scans/{scanId}	Scan status & results
GET	/api/v1/scans/{scanId}/stream	SSE progress stream
POST	/api/v1/scans/{scanId}/analyze	Analyze dead code candidates
POST	/api/v1/scans/{scanId}/patches	Generate patch proposals
GET	/api/v1/patches/{patchId}	Retrieve patch details / diffs
POST	/api/v1/patches/{patchId}/apply	Apply patch (requires confirm)
POST	/api/v1/patches/{patchId}/verify	Verify patch via replay
GET	/api/v1/patches/{patchId}/verify/stream	SSE verification progress
POST	/api/v1/patches/{patchId}/rollback	Rollback to pre-patch state
GET	/api/v1/health	Health check

Architecture

Cursor (MCP)  /  CLI  /  REST client
        |                    |
   MCP Server           FastAPI Server
   (codereaper.mcp)     (codereaper.api)
        \                  /
         \                /
      Shared Services Layer
      (scanner, analyzer, patcher, verifier)
              |                |
    Index Browser Agent    V8 CDP Coverage
    (autonomous UI         (precise per-function
     exploration)           execution counts)

Pipeline

Phase	Description
1. Scan & Explore	Launch Index agent to autonomously interact with all UI surfaces while collecting V8 coverage
2. Analyze	Map coverage ranges to functions, classify executed vs. unexecuted, detect dynamic references
3. Patch	Generate unified diffs with rationale and risk scores
4. Verify	Replay the original interaction plan against patched code, detect regressions
5. Rollback	Restore original files from pre-patch snapshots

Project Structure

codereaper/
├── __main__.py              # python -m codereaper -> MCP server
├── mcp/                     # MCP server for Cursor
│   ├── __init__.py          # main() entry point
│   ├── __main__.py          # python -m codereaper.mcp
│   └── server.py            # FastMCP tools
├── api/                     # REST API (FastAPI)
│   ├── __init__.py          # main() entry point
│   ├── __main__.py          # python -m codereaper.api
│   ├── app.py               # FastAPI app, lifespan, CORS
│   └── routers/
│       ├── scans.py         # Scan + analyze endpoints
│       └── patches.py       # Patch + verify + rollback endpoints
├── services/                # Shared business logic
│   ├── scanner.py           # Index agent orchestration + CDP coverage
│   ├── analyzer.py          # Coverage mapping + dead code detection
│   ├── patcher.py           # Diff generation + application + rollback
│   └── verifier.py          # Replay + regression detection
├── models/
│   ├── schemas.py           # Pydantic request/response models
│   └── enums.py             # Status, risk, safety enums
├── core/
│   ├── config.py            # Settings via pydantic-settings
│   ├── storage.py           # SQLite + filesystem artifact storage
│   └── sse.py               # SSE event helpers + channel
└── tests/

bin/cli.mjs                  # npx wrapper (spawns uvx/pipx/python)
pyproject.toml               # Python packaging (pip install codereaper)
package.json                 # npm packaging (npx codereaper)

Tech Stack

• MCP Server: FastMCP
• REST Server: FastAPI + Uvicorn
• Validation: Pydantic v2
• Storage: aiosqlite + filesystem
• Browser: Playwright (via Index agent)
• Coverage: V8 CDP Profiler domain
• Diff: Python difflib
• SSE: StreamingResponse with text/event-stream