code-review-graph

AI coding tools re-read your entire codebase on every task. code-review-graph fixes that. It builds a structural map of your code with Tree-sitter, tracks changes incrementally, and gives your AI assistant precise context via MCP so it reads only what matters.

Quick Start

pip install code-review-graph                     # or: pipx install code-review-graph
code-review-graph install          # auto-detects and configures all supported platforms
code-review-graph build            # parse your codebase

One command sets up everything. install detects which AI coding tools you have, writes the correct MCP configuration for each one, and injects graph-aware instructions into your platform rules. It auto-detects whether you installed via uvx or pip/pipx and generates the right config. Restart your editor/tool after installing.

To target a specific platform:

code-review-graph install --platform codex       # configure only Codex
code-review-graph install --platform cursor      # configure only Cursor
code-review-graph install --platform claude-code  # configure only Claude Code
code-review-graph install --platform kiro         # configure only Kiro

Requires Python 3.10+. For the best experience, install uv (the MCP config will use uvx if available, otherwise falls back to the code-review-graph command directly).

Then open your project and ask your AI assistant:

Build the code review graph for this project

The initial build takes ~10 seconds for a 500-file project. After that, the graph updates automatically on every file edit and git commit.

How It Works

Your repository is parsed into an AST with Tree-sitter, stored as a graph of nodes (functions, classes, imports) and edges (calls, inheritance, test coverage), then queried at review time to compute the minimal set of files your AI assistant needs to read.

Blast-radius analysis

When a file changes, the graph traces every caller, dependent, and test that could be affected. This is the "blast radius" of the change. Your AI reads only these files instead of scanning the whole project.

Incremental updates in < 2 seconds

On every git commit or file save, a hook fires. The graph diffs changed files, finds their dependents via SHA-256 hash checks, and re-parses only what changed. A 2,900-file project re-indexes in under 2 seconds.

The monorepo problem, solved

Large monorepos are where token waste is most painful. The graph cuts through the noise — 27,700+ files excluded from review context, only ~15 files actually read.

23 languages + Jupyter notebooks

Full Tree-sitter grammar support for functions, classes, imports, call sites, inheritance, and test detection in every language. Includes Zig, PowerShell, Julia, and Svelte SFC support. Plus Jupyter/Databricks notebook parsing (.ipynb) with multi-language cell support (Python, R, SQL), and Perl XS files (.xs).

Benchmarks

All numbers come from the automated evaluation runner against 6 real open-source repositories (13 commits total). Reproduce with code-review-graph eval --all. Raw data in evaluate/reports/summary.md.

The graph replaces reading entire source files with a compact structural context covering blast radius, dependency chains, and test coverage gaps.

| Repo | Commits | Avg Naive Tokens | Avg Graph Tokens | Reduction | |------|--------:|-----------------:|----------------:|----------:| | express | 2 | 693 | 983 | 0.7x | | fastapi | 2 | 4,944 | 614 | 8.1x | | flask | 2 | 44,751 | 4,252 | 9.1x | | gin | 3 | 21,972 | 1,153 | 16.4x | | httpx | 2 | 12,044 | 1,728 | 6.9x | | nextjs | 2 | 9,882 | 1,249 | 8.0x | | Average | 13 | | | 8.2x |

Why express shows <1x: For single-file changes in small packages, the graph context (metadata, edges, review guidance) can exceed the raw file size. The graph approach pays off on multi-file changes where it prunes irrelevant code.

The blast-radius analysis never misses an actually impacted file (perfect recall). It over-predicts in some cases, which is a conservative trade-off — better to flag too many files than miss a broken dependency.

| Repo | Commits | Avg F1 | Avg Precision | Recall | |------|--------:|-------:|--------------:|-------:| | express | 2 | 0.667 | 0.50 | 1.0 | | fastapi | 2 | 0.584 | 0.42 | 1.0 | | flask | 2 | 0.475 | 0.34 | 1.0 | | gin | 3 | 0.429 | 0.29 | 1.0 | | httpx | 2 | 0.762 | 0.63 | 1.0 | | nextjs | 2 | 0.331 | 0.20 | 1.0 | | Average | 13 | 0.54 | 0.38 | 1.0 |

| Repo | Files | Nodes | Edges | Flow Detection | Search Latency | |------|------:|------:|------:|---------------:|---------------:| | express | 141 | 1,910 | 17,553 | 106ms | 0.7ms | | fastapi | 1,122 | 6,285 | 27,117 | 128ms | 1.5ms | | flask | 83 | 1,446 | 7,974 | 95ms | 0.7ms | | gin | 99 | 1,286 | 16,762 | 111ms | 0.5ms | | httpx | 60 | 1,253 | 7,896 | 96ms | 0.4ms |

• Small single-file changes: Graph context can exceed naive file reads for trivial edits (see express results above). The overhead is the structural metadata that enables multi-file analysis.
• Search quality (MRR 0.35): Keyword search finds the right result in the top-4 for most queries, but ranking needs improvement. Express queries return 0 hits due to module-pattern naming.
• Flow detection (33% recall): Only reliably detects entry points in Python repos (fastapi, httpx) where framework patterns are recognized. JavaScript and Go flow detection needs work.
• Precision vs recall trade-off: Impact analysis is deliberately conservative. It flags files that might be affected, which means some false positives in large dependency graphs.

Features

| Feature | Details | |--