code-review-graph: a local code graph that trims what your AI assistant reads

The token waste code-review-graph targets

A review request to an AI coding tool often turns into a full-repository read. The model opens files, follows imports by guessing, and pulls in modules that have no relationship to the change under discussion. The README frames the problem plainly: AI coding tools can re-read large parts of a codebase on review tasks. The cost is measured in context window space and in the quality of the answer, because a model drowning in unrelated source has less room for the diff that matters.

code-review-graph is aimed at engineers working in repositories big enough for that to hurt, and at the tooling around MCP-capable assistants. It is not a linter, not a CI gate and not a replacement for human review. It is a retrieval layer: it decides which files are relevant to a change and hands that subset to the assistant. The README's own framing of the payoff is a slice rather than a corpus, and it quotes a figure for this repository where 208,821 source tokens become roughly 3,190 tokens per question.

Tree-sitter parse, graph store, blast-radius query

The mechanism has three stages. First, each source file is parsed into an abstract syntax tree with Tree-sitter. Second, the parse is flattened into a graph: nodes are functions, classes and imports, edges are calls, inheritance and test coverage. Third, at review time the graph is queried to compute the minimal set of files the assistant needs.

The query that does the work is called blast-radius analysis. When a file changes, the graph walks callers, dependents and tests that could be affected, and that reachable set is what gets returned. This is the part worth understanding, because it defines both the value and the failure mode. A blast radius computed from static call and import edges will miss anything reached through dynamic dispatch, string-based imports, reflection or runtime registration. The README does not claim otherwise, but it also does not document a fallback for those cases, so a reader should treat the returned file set as a lower bound on relevance rather than a complete answer.

Updates are incremental. When hooks or watch mode are enabled, a file save or a supported commit hook triggers a diff, the graph finds dependents through its own import and call edges, and only files whose SHA-256 hash actually changed are re-parsed. The README gives a concrete measurement for a two-file edit on a roughly 3,000-file project (django): about 2.5 seconds on the path the hooks use, of which about 1.4 seconds is process start-up. A no-op update costs only that start-up. That start-up overhead is the number to watch, because it is paid on every hook invocation regardless of how much changed.

Installing code-review-graph and running a first build

The package is on PyPI and requires Python 3.10 or newer. The README gives pip and pipx as install paths, and notes that installing uv gives a better experience because the generated MCP configuration will use uvx when it is available and fall back to the code-review-graph command otherwise.

pip install code-review-graph

After installation, one command does the integration work. According to the README, install detects which AI coding tools you have, writes the correct MCP configuration for each, installs platform-native hooks and skills where supported, and injects graph-aware instructions into your platform rules. It also detects whether you installed through uvx or pip/pipx and generates the matching config.

code-review-graph install

If you would rather configure one tool, the install command takes a platform flag. The README lists codex, cursor, claude-code, gemini-cli, antigravity, windsurf, zed and continue among the accepted values.

code-review-graph install --platform claude-code

Restart your editor or tool after installing. Then build the graph for the project, which the README says takes about 10 seconds for a 500-file project.

code-review-graph build

With the graph built, the README's suggested first interaction is a natural-language request to the assistant, not a CLI call: ask it to build the code review graph for the project. From that point on, watch mode and supported hooks keep the graph current without a manual rebuild. Removal is symmetric and has a preview mode, which is the right way to inspect what the tool wrote before accepting it.

code-review-graph uninstall --dry-run

Where the graph model breaks down

The honest limitation is that a static graph is a model of your code, and models of code are wrong in predictable ways. Languages with heavy metaprogramming produce call edges that Tree-sitter cannot resolve. A Python project leaning on decorators, entry-point registries or importlib will have real dependencies that never appear as an import statement, so the blast radius under-reports and the assistant may be handed a slice that is missing the file it needed. The README lists a wide parser surface, including Python, JavaScript/TypeScript/TSX, Go, Rust, Java, C/C++, C#, VB.NET, Ruby, Kotlin, Swift, PHP, Scala, Solidity, Dart, R, Perl, Lua/Luau, Objective-C, shell, Elixir, Zig, PowerShell, Julia, ReScript, GDScript, Nix, Verilog/SystemVerilog, SQL, Terraform/OpenTofu structure, Ansible playbooks, Vue and Svelte single-file components, Astro, Jupyter and Databricks notebooks, and Perl XS files. Breadth here is not the same as depth: generic YAML is explicitly not treated as source code, and generic .hcl files are recognized only as file nodes rather than parsed for structure.

There is also a cost the README does not quantify. A persistent graph database is another artifact in your working tree, and the uninstall documentation implies CRG-owned files and entries exist in your project and in per-tool configuration. The uninstall command is careful about this, normalizing the target to the working tree root, refusing non-repository directories, leaving unrelated MCP servers, hooks, skills and JSONC comments untouched, and using atomic replacement for shared configuration so a failed write leaves the original intact. That is a good sign, but it also tells you the install command writes into shared config files, which is exactly the kind of change that should be reviewed rather than run blind.

Finally, the project is Beta by its own classifier in pyproject.toml. The dependency pins reflect that: fastmcp is constrained to >=3.2.4,<4 with a comment noting that fastmcp 3.0 broke the server, and mcp is pinned to >=1.0.0,<3. Those upper bounds are deliberate protection, and they also mean a future major release of either dependency will require a coordinated change here.

How it differs from a plain language server or a grep-based context tool

The obvious alternative is a language server plus whatever context selection your assistant already does. A language server answers precise questions about symbols, references and types, and it is usually better than a graph at resolving a single symbol correctly. The difference is the unit of work. A language server answers one query at a time; code-review-graph computes a whole reachable set for a change and hands that set over in one shot, which is what an MCP tool call needs. If your workflow is interactive symbol navigation, a language server is the better tool and the graph adds little.

The other alternative is a semantic or embedding-based retrieval layer over the repository. That approach indexes text and returns chunks by similarity, so it handles prose, configuration and dynamically wired code that a call graph cannot see. It also returns chunks that are semantically near the question but structurally unrelated, which is the exact failure the graph is built to avoid. The trade-off is legibility: a blast radius can be explained by walking edges, while a similarity score cannot. Neither approach is a reviewer. If what you want is an opinion on a diff, both are plumbing underneath a model that supplies the opinion.

Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-08-21, which is under a month before today's date, so recent activity is real rather than assumed. The release history shows v2.3.8 on 2026-08-21, v2.3.7 on 2026-07-18 and v2.3.6 on 2026-06-10, the last of which is labelled a community-response release. A roughly monthly cadence on a Beta project means you should expect to re-run code-review-graph install after upgrades, since the install command is what writes MCP configuration, hooks and platform rules, and those outputs can change between versions.

The licence is MIT, declared both in the README badge and in pyproject.toml. That is permissive: you can use, modify and redistribute the code, including in commercial settings, provided the copyright notice and permission notice are preserved. This is a factual description of the licence text, not legal advice, and if you are redistributing it inside a product you should have your own counsel read the actual LICENSE file rather than a summary.

The upgrade cost that matters is not the Python package. It is the graph database and the configuration the tool writes into your editors. The uninstall command supports --keep-data to remove integrations while keeping graph databases, and --all-repos to clean every registered repository, which suggests the tool maintains a registry of repositories it has touched. If you install it across several projects, that registry is the thing to understand before you decide how to remove it.

Editorial conclusion

Adopt code-review-graph if you run an MCP-capable assistant over a repository large enough that whole-corpus reads are the bottleneck, and you are willing to keep a graph database in sync through hooks or watch mode. Skip it if your project is small, if you use an editor the install command does not list, or if you want an actual reviewer rather than a retrieval layer; the graph returns context, it does not judge code. Before trusting it, run code-review-graph build on a branch, confirm the parser covers your primary language, and check that code-review-graph uninstall --dry-run lists only files you expect it to touch.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes