# Code Review Graph code-review-graph (CRG) builds a persistent structural map of your codebase so AI coding tools read only what matters. Local-first, exposed over [[Model Context Protocol (MCP)|MCP]] and a CLI. By tirth8205, [[MIT License]], [[Python]]. Its tagline: *"Stop burning tokens. Start reviewing smarter."* ## The problem it targets Ask a coding agent "how does authentication work" and it greps, reads a dozen files, follows imports, reads a dozen more. Every review task re-derives structure the repository already encodes. You pay for that rediscovery on every question, in tokens and in latency. CRG parses the repo once into an AST with [[Tree-sitter]], stores it as a graph of nodes (functions, classes, imports) and edges (calls, inheritance, test coverage), then queries that graph at review time to compute the minimal set of files the agent actually needs. ## How it works **Blast-radius analysis.** When a file changes, the graph traces every caller, dependent and test that could be affected. The agent reads that set rather than scanning the project. **Incremental updates.** Hooks and watch mode re-index on save. It diffs changed files, finds dependents through its own import and call edges, and re-parses only files whose SHA-256 actually changed. On a ~3,000-file project a two-file edit re-indexes in about 2.5 seconds, of which ~1.4s is process start-up. **Broad language coverage.** Tree-sitter across roughly 30 languages, plus Jupyter notebooks, Vue/Svelte SFCs, Terraform, Ansible, and PHP extras like Composer PSR-4 resolution and Laravel Route/Eloquent edges. If your language isn't covered, a `languages.toml` maps extensions to any bundled grammar with no fork required. **One-command setup across tools.** `code-review-graph install` auto-detects your AI coding tools and writes the right MCP config for each: [[Claude Code]], [[Codex CLI]], Cursor, Gemini CLI, [[Windsurf]], Zed, Continue, [[OpenCode]], Qwen, Qoder, Kiro, GitHub Copilot, CodeBuddy. The `uninstall` is symmetric, supports `--dry-run`, and touches only CRG-owned entries. ```bash pip install code-review-graph code-review-graph install code-review-graph build ``` **CI reviews.** The same analysis runs as a composite [[GitHub Actions|GitHub Action]] that posts one sticky comment per PR with risk-scored functions, affected execution flows and test gaps, updated in place. `fail-on-risk` turns it into a merge gate. The graph is built and queried entirely on your runner; no source leaves it. ## The benchmarks, and why they're the interesting part Headline: **~65× median per-question token reduction** across 6 real open-source repos, range 36× to 376×. On its own repository, 208,821 corpus tokens become ~3,190 tokens per question. But the reason I'm writing this down is *how the numbers are presented*: - **The 376× best case is explicitly disowned as the headline.** "376x is a single best-case repo (fastapi, the largest corpus) — not the typical result." Most projects would have put 376× on the front page - **A recall of 1.0 is labelled circular.** Blast-radius analysis recovers every file in the ground truth, and the README says plainly to read that as an upper bound, because the ground truth is derived from the same graph the predictor traverses. Average F1 is quoted honestly at 0.69, with precision 0.55, and the over-prediction is named as a deliberate trade-off - **A benchmark that doesn't work yet is reported as not working.** The co-change mode grades against files the author actually touched, independent of the graph. It currently returns zero predictions on every commit, so no number is quoted and the harness is described as needing fixing - **The baseline is described as unfair to itself.** The whole-corpus comparison is called "an upper bound no real agent pays", since a competent agent greps first, and a separate `agent_baseline` benchmark measures that realistic case - **A second benchmark that makes it look bad is kept.** `token_efficiency.py` reports ratios below 1 for small commits, and the README explains why rather than dropping it - **Numbers went down and it says so.** The 2026-08-02 re-capture is lower than the 2026-05-25 one because node embedding text got richer Reproducibility is pinned upstream SHAs, a fixed seed for the community detector, and deterministic CPU embeddings, so two machines produce identical numbers. ## Why I keep this note **This is the benchmark README I'd hold everything else to.** I spent today reading vendor tables where the baseline was a crippled version of the vendor's own product ([[JCode]]), where in-house evals were unfalsifiable ([[Qwen 3.8]]), and where a 99%-lower-cost claim rested on "estimated cost per task" ([[GPT-5.6]]). This one argues *against* its own best number, labels its perfect score circular, and publishes a broken benchmark as broken. That is what credibility looks like, and it costs nothing but the willingness to be less impressive. **Structural indexing is the right answer to context cost.** The interesting move isn't compression or a bigger window, it's precomputing what the agent would otherwise rediscover. The repo already contains the call graph; parse it once and query it. Same shape as [[varlock]] making the schema the artifact rather than the values: put the structure somewhere addressable and stop re-deriving it. **And it's an MCP server that earns its context.** Most of what I connect adds tools whose descriptions cost tokens on every turn. This one exists specifically to *reduce* what gets read. Worth pointing at a large repo and measuring, which the `context_savings` estimate and `--verify` against `cl100k_base` make possible. The caveat: it's another daemon-ish thing to install, an index to keep fresh, and a dependency in your review path. On a small repo the whole premise is moot, since an agent grepping a 50-file project was never the problem. ## References - [tirth8205/code-review-graph](https://github.com/tirth8205/code-review-graph) — source - [Reproducing the benchmarks](https://github.com/tirth8205/code-review-graph/blob/main/docs/REPRODUCING.md) — full methodology - [GitHub Action docs](https://github.com/tirth8205/code-review-graph/blob/main/docs/GITHUB_ACTION.md) - [Custom languages](https://github.com/tirth8205/code-review-graph/blob/main/docs/CUSTOM_LANGUAGES.md) - [Tree-sitter](https://tree-sitter.github.io/tree-sitter/) ## Related - [[Model Context Protocol (MCP)]] - [[Tree-sitter]] - [[Context Engineering]] - [[Context Window]] - [[Claude Code]] - [[Codex CLI]] - [[OpenCode]] - [[Windsurf]] - [[GitHub Actions]] - [[AI Agents]] - [[Python]] - [[Open Source]] - [[MIT License]]