code-review-graph: A Local Graph That Tells Your AI Which Files to Read

The Token Waste Problem in AI Code Review

The tool is for engineers who use AI assistants inside editors like Cursor, Codex, or Claude Code, and who have hit context limits or token costs on review tasks. It is not for everyone. If your project has fifty files, the overhead of building and maintaining a graph likely outweighs the savings. The target user is someone with a multi-thousand-file codebase where every extra token matters.

Tree-sitter Graph and Blast-Radius Analysis

The core mechanism is a structural map built with Tree-sitter. The README describes it as a graph of nodes (functions, classes, imports) and edges (calls, inheritance, test coverage). When a file changes, the graph traces every caller, dependent, and test that could be affected. That set of files is the blast radius. The AI assistant receives only those files, not the whole project. This is a different approach from simple file listing or grep-based context gathering. The graph's edges are what make the difference. If the graph is accurate, the AI reads exactly what matters. If an edge is missing, the AI might miss a dependency. The documentation does not specify how edge extraction handles dynamic dispatch or reflection, so there is an inherent risk of incomplete edges in languages with heavy metaprogramming.

Incremental Updates: Fast, but with a Catch

The graph updates incrementally. The README reports that on a ~3,000-file project like django, a two-file edit re-indexes in about 2.5 seconds, of which ~1.4 seconds is process start-up. A no-op update costs only that start-up. This is achieved by hashing files with SHA-256 and re-parsing only those whose hash changed. The graph diffs changed files, finds dependents through import and call edges, and updates the relevant nodes. This is a sensible design. However, the 2.5-second figure includes process start-up, which means the actual parsing time is about 1.1 seconds. If you invoke the tool from a hook on every save, that start-up cost is paid every time. The README does not state whether the MCP server keeps a long-running process that avoids start-up, or whether each hook invocation is a fresh process. That distinction matters for real-world latency.

Setup: One Command, Many Platforms

Installation is straightforward. You need Python 3.10 or later. The README recommends installing uv for the best experience, because the MCP config will use uvx if available, otherwise it falls back to the code-review-graph command directly. The quick start is three commands: pip install code-review-graph, then code-review-graph install, then code-review-graph build. The install command auto-detects which AI coding tools you have and writes the correct MCP configuration for each one. It also installs platform-native hooks and skills where supported, and injects graph-aware instructions into platform rules. You can target a specific platform with --platform codex, cursor, claude-code, gemini-cli, antigravity, windsurf, zed, or continue. After install, you restart your editor and ask your AI assistant to 'Build the code review graph for this project'. The initial build takes about 10 seconds for a 500-file project.

Uninstall: Symmetric and Safe, but Verify

The uninstall command is designed to be safe. It removes only CRG-owned files and entries, leaving unrelated MCP servers, hooks, skills, and JSONC comments untouched. It uses atomic replacement for shared configuration changes, so a failed write leaves the original file intact. You can preview with --dry-run, then apply with confirmation, or use --yes to skip the prompt. There are options to clean all registered repositories with --all-repos, keep graph data with --keep-data, or clean only the current project. This is a thoughtful design. However, the README warns that non-repository directories are refused, and the target is normalized to the working tree root. If you have a monorepo with nested repositories, you need to run the command from the correct root. The safety of uninstall depends on the tool correctly identifying its own files. The README says it does, but you should still run --dry-run first to see exactly what it will remove.

Language Coverage: Broad but with Gaps

The parser support is extensive. It covers 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 scripts, Elixir, Zig, PowerShell, Julia, ReScript, GDScript, Nix, Verilog/SystemVerilog, SQL, Terraform/OpenTofu structure, Ansible playbooks, Vue/Svelte SFCs, Astro files, Jupyter notebooks, and Perl XS files. That is a long list. But the README also notes that generic YAML is not treated as source code, and generic .hcl files are recognized as file nodes only. This means if your project relies heavily on YAML for configuration or .hcl for HashiCorp tooling, the graph will not give you the same level of detail. The README mentions 'targeted fallbacks' where Tree-sitter is not available, but does not specify which languages use fallbacks or how accurate they are. For a language like SQL, the graph likely only sees file-level nodes, not function-level calls. This is a real limitation for polyglot repositories.

Alternatives: What Else Does This Job?

The closest alternative is a plain context-packing tool like repo-map or a simple file listing script that feeds all changed files plus their imports to the AI. That approach has no graph, so it cannot compute blast radius. It will either over-include files (wasting tokens) or under-include them (missing dependencies). Another alternative is a semantic search tool like ripgrep combined with an AI prompt that asks the model to find relevant files. That is cheap and language-agnostic, but it does not track call graphs or inheritance. code-review-graph's advantage is the explicit edge structure. The trade-off is that you must trust the graph's construction. For a project that relies on dynamic imports or runtime dispatch, a grep-based approach might actually be more reliable because it does not pretend to know the call graph. The README does not compare itself to these alternatives, but the choice is clear: if you want deterministic blast radius, you need a graph; if you accept probabilistic relevance, grep is simpler.

Maintenance and License

The project is MIT-licensed, which means you can use it in commercial products with few restrictions. The repository is active, with the latest release v2.3.8 pushed on 2026-08-21. The release history shows a steady cadence: v2.3.7 in July, v2.3.6 in June, which was described as a 'community-response release'. That suggests the maintainers listen to feedback. Maintenance cost is a real consideration. The graph database persists locally, and you need to keep it updated. The README mentions watch mode and hooks, but you must ensure those are running in your CI or local environment. If you forget to update the graph, your AI will work with stale edges. The uninstall command helps with cleanup, but you still need to manage the graph data size. The README does not state how large the graph database grows or whether there is a pruning mechanism. For a very large repository, the initial build time of 10 seconds for 500 files scales linearly, so a 5,000-file project might take 100 seconds. That is acceptable for a one-time build, but you should budget for it.

Editorial conclusion

Adopt code-review-graph if you work in a large repository with many files, use an MCP-capable AI tool like Codex or Cursor, and want to reduce token consumption on review tasks. Skip it if your project is small, if you cannot keep the graph updated, or if you need precise cross-language analysis beyond the parser surface. Before adopting, verify that your languages are fully supported, that the incremental update latency on your hardware matches the documented ~2.5 seconds for a two-file edit, and that the uninstall command leaves your editor config intact. The project is MIT-licensed and actively maintained, but the real test is whether the blast-radius edges match your mental model of the codebase.

Official sources

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