Ask a coding agent to review a pull request and, without help, it often ends up reading far more of the codebase than the change actually touches — every file gets pulled into context just so the agent can reason about what might be affected. code-review-graph fixes that by building a persistent, structural map of a codebase ahead of time, so an AI coding tool can query precisely what's relevant through MCP instead of re-reading files it doesn't need.
Built on Tree-sitter, Updated Incrementally
The core mechanism is a structural graph parsed with Tree-sitter across a genuinely broad set of languages and frameworks — Python, JavaScript, Rust, Go, PHP/Laravel, Java, C#, Terraform, Ansible, and more — plus Jupyter notebook support. The graph updates incrementally rather than requiring a full re-parse on every change, which is what makes it practical to keep current on an actively-developed repository rather than something you rebuild from scratch each session. Once built, a single install command auto-detects which AI coding tools are present — Claude Code, Cursor, Codex, Windsurf, Zed, GitHub Copilot, and over a dozen others — and writes the correct MCP configuration for each one automatically.
Blast-Radius Analysis Is the Actual Value Proposition
Beyond just answering "what does this function do," the graph supports blast-radius analysis — tracing which files and functions are affected by a given change through call and import edges, so a review tool can flag downstream impact instead of only looking at the diff in isolation. That's the harder, more valuable problem token-efficient retrieval is actually solving for: knowing what to check, not just answering questions faster about what's already open.
The Benchmark Numbers Are Reported With Real Honesty
This is the part worth taking seriously as a model for how technical claims should be published. The headline number — a ~65x median per-question token reduction across six real repositories — comes with a documented, reproducible methodology (pinned commit SHAs, a fixed random seed, deterministic CPU embeddings) rather than an unverifiable marketing figure, and the project is explicit that the 376x maximum is a single best-case result on the largest test corpus, not the typical outcome. More notably, the "Limitations and known weaknesses" section is genuinely substantive rather than boilerplate: it states directly that the impact-analysis "recall 1.0" figure is circular by construction (the ground truth is derived from the same graph the predictor traverses), that a more honest co-change evaluation mode currently returns zero predicted files on every graded commit and isn't yet a usable measurement, and that search ranking quality (MRR 0.35) and flow detection accuracy (33% recall) both need work in specific named areas. A project willing to publish "this evaluation mode doesn't work yet" in its own README is a stronger signal of engineering integrity than a clean benchmark table with no caveats would be.
What's Actually in the Graph
The graph isn't a vague "index" — it's a concrete structure with typed nodes and edges. Nodes represent functions, classes, and imports; edges represent calls, inheritance, and test coverage. That's parsed straight out of the Tree-sitter AST and stored in SQLite, which is what makes both the blast-radius traversal and the incremental updates tractable: querying "what calls this function" or "what tests cover this class" is a graph query against structured data, not a fresh text search over source files every time.
Incremental updates lean on the same structure. When a hook or watch mode fires, the tool diffs changed files against Git, walks the graph's own import and call edges to find dependents, and re-parses only the files whose SHA-256 hash actually changed — untouched files are skipped entirely rather than re-hashed and re-walked for no reason. On django, a roughly 3,000-file repository, a two-file edit re-indexes in about 2.5 seconds on the hook path, and close to 1.4 seconds of that is process start-up rather than parsing work; a no-op update (nothing actually changed) costs only that start-up overhead. That's a meaningfully different cost profile than a full re-parse on every save, and it's the detail that makes "keep the graph current on an actively-developed repo" a realistic claim rather than an aspiration.
Build performance scales with repo size in a predictable way: express (141 files) builds its graph — 1,910 nodes, 17,553 edges — in around 106ms with sub-millisecond search latency, while fastapi (1,122 files) takes about 128ms to produce 6,285 nodes and 27,117 edges. Even at the larger end, initial build stays fast enough to run as a normal part of getting started rather than something you kick off and walk away from.
Extending Language Support Without Forking
Tree-sitter coverage is already broad — Python, JavaScript/TypeScript, Go, Rust, Java, C/C++, C#, VB.NET, Ruby, Kotlin, Swift, PHP, Scala, Solidity, Dart, R, Perl, Lua, Objective-C, shell scripts, Elixir, Zig, PowerShell, Julia, Terraform/OpenTofu structure, Ansible playbooks, Vue/Svelte SFCs, and more — but the project doesn't require a fork when a codebase uses something the built-in parsers don't cover. Dropping a languages.toml file into .code-review-graph/ that maps file extensions to a grammar bundled in tree_sitter_language_pack, plus the specific Tree-sitter node types for functions, classes, imports, and calls, is enough for the generic tree-sitter walker to start extracting structure from that language — no code changes required, and the built-in language definitions can't be overridden by a misconfigured custom entry. PHP gets extra treatment beyond generic Tree-sitter parsing: repository-bounded Composer PSR-4 resolution, Blade template references, and Laravel-specific Route and Eloquent semantic edges when the source shows explicit framework imports and model inheritance.
Risk-Scored Reviews Inside CI, Not Just Locally
Beyond the MCP integration for interactive coding sessions, the same analysis ships as a composite GitHub Action that runs entirely on the CI runner — the knowledge graph is built and queried locally in that job, with no source code sent to an external service. On each pull request it posts a single sticky comment listing risk-scored functions, affected execution flows, and test gaps, and that comment updates in place on every subsequent push rather than accumulating a new comment each time. An optional fail-on-risk input turns the review from an informational comment into an actual merge gate. The project dogfoods this on itself, running the same action against its own pull requests rather than only recommending it for other repos.
Practical Implications
- The token-reduction claim is real but scenario-dependent. For small, single-file changes, the project's own data shows graph context can actually exceed a naive file read — the overhead is the structural metadata that only pays off once multiple files or dependency reasoning are involved. Don't expect the headline multiplier on every commit.
- Blast-radius analysis trades precision for recall on purpose. It's designed to over-flag potentially-affected files rather than risk missing a broken dependency — treat its output as a review starting point, not a definitive list.
- Search quality varies significantly by construct naming convention — the project specifically notes that Express queries return zero hits due to how that framework's modules are typically named, which is a useful reminder that any code-graph tool's quality depends partly on how idiomatically a given codebase is structured.
- The reproduction recipe is a real asset if you're evaluating this seriously. Documented, pinned-SHA benchmarks you can rerun yourself are worth actually running before trusting the numbers for your own codebase's language and structure.
Practical Takeaway
code-review-graph is a well-engineered answer to a real, specific cost problem in AI-assisted code review: agents re-reading far more of a codebase than a change actually requires. What sets it apart isn't just the token-efficiency numbers — plenty of tools claim efficiency gains — it's the unusually transparent disclosure of exactly where the measurements are weak, circular, or not yet trustworthy. For teams evaluating AI code review tooling or building GraphRAG-style context systems of their own, that honesty is worth as much as the benchmark table itself when deciding whether to trust the claims.
Teams building code-intelligence infrastructure or evaluating MCP-based context tooling for AI coding agents can get hands-on architecture help from Woyce Technologies.
FAQ
What is code-review-graph?
code-review-graph is an open-source tool that builds a persistent, Tree-sitter-based structural graph of a codebase and serves precise, relevant context to AI coding tools via MCP, reducing how much of the codebase an agent needs to read for reviews and impact analysis.
How much does code-review-graph actually reduce token usage?
Its published benchmarks show a median ~65x per-question token reduction across six real open-source repositories, with a documented, reproducible methodology. The maximum measured reduction (376x) is a single best-case result, not the typical outcome — for small single-file changes, the reduction can be smaller or even negative.
Which AI coding tools does code-review-graph support?
It auto-detects and configures MCP integration for a wide range of tools including Claude Code, Cursor, Codex, Windsurf, Zed, GitHub Copilot, and over a dozen others, writing the correct configuration for each automatically.
Is code-review-graph free to use?
Yes, it's MIT-licensed and open source, installable via pip or pipx and distributed on PyPI.
What is blast-radius analysis?
It's the graph's ability to trace which files and functions are likely affected by a given code change through call and import relationships, so a review tool can flag downstream impact rather than only examining the diff in isolation.
What are code-review-graph's known limitations?
The project's own documentation discloses several: its headline impact-analysis recall figure is circular by construction, a more honest co-change evaluation mode isn't yet a usable measurement, search ranking quality and flow detection accuracy both need improvement in specific languages, and token savings can be negative for small single-file changes.
How does code-review-graph handle a language it doesn't support out of the box?
You can add one without forking the project: a languages.toml file in .code-review-graph/ maps file extensions to a grammar already bundled in tree_sitter_language_pack, along with the Tree-sitter node types for functions, classes, imports, and calls. The generic parser handles extraction from there.
Does code-review-graph work with GitHub Actions?
Yes — it ships as a composite GitHub Action that builds and queries the graph locally on the CI runner and posts a single sticky risk-review comment on each pull request, updated in place on every push. An optional fail-on-risk input can turn it into a merge gate.
How fast are incremental updates on a large repository?
On django, a roughly 3,000-file repo, a two-file edit re-indexes in about 2.5 seconds through the hook path, of which roughly 1.4 seconds is process start-up rather than parsing. A no-op update costs only that start-up overhead, since only files with a changed SHA-256 hash get re-parsed.
Is code-review-graph's analysis sent to an external service?
No — both the CLI/MCP workflow and the GitHub Action build and query the graph locally. The GitHub Action explicitly runs the knowledge graph construction and querying on the CI runner itself, with no source code sent externally.