code-review-graph: local-first LLM context for code review
tirth8205/code-review-graph
code-review-graph is a local-first knowledge graph that feeds your AI coding assistant only the files a change actually touches, instead of the whole repo. Reach for it if you're already paying for Claude Code, Cursor, or Copilot tokens on large-repo reviews and want blast-radius context instead of grep guesses. Skip it if your codebase is small enough that an agent reading everything is already fast and cheap.
The Challenge of LLM Context in Code Review
AI code review tools re-read whole files or whole repos to answer a question an experienced developer could settle by tracing three function calls. On a repo the size of fastapi, a naive whole-corpus read costs 948,793 tokens for something the README's own benchmark answers in about 2,653 tokens through a graph query — the gap between what an LLM needs to see and what it's actually handed is the real cost driver, not the size of the model's context window.
Introducing code-review-graph
code-review-graph is a CLI and MCP server that parses your codebase with Tree-sitter into a graph of functions, classes, imports, and call edges, then serves an AI assistant only the slice relevant to a given change. It ships as a pip/pipx package, configures itself against tools like Claude Code, Cursor, Codex, and GitHub Copilot, and keeps everything in a local SQLite file rather than a hosted service.
Core Features and Capabilities
- ✓Blast-radius analysis traces every caller, dependent, and test affected by a changed file, so the assistant reads only those instead of scanning the project.
- ✓Incremental updates re-parse only files whose SHA-256 hash changed; a two-file edit on a ~3,000-file project like Django re-indexes in about 2.5 seconds, ~1.4s of which is process start-up.
- ✓Tree-sitter parsing covers a long list of languages including Python, JavaScript/TypeScript/TSX, Go, Rust, Java, C/C++, C#, Ruby, Kotlin, Swift, PHP, and Jupyter notebooks (.ipynb), with a languages.toml escape hatch for anything missing.
- ✓PHP projects get repository-bounded Composer PSR-4 resolution plus Laravel Route-to-controller and Eloquent edges when the source shows the framework evidence.
- ✓A GitHub Action runs the same graph analysis on your CI runner and posts a single sticky PR comment with risk-scored functions and test gaps, with an optional fail-on-risk merge gate.
- ✓Semantic search layers vector embeddings from sentence-transformers, Google Gemini, MiniMax, or any OpenAI-compatible endpoint on top of FTS5 keyword search.
- ✓Community detection via the Leiden algorithm clusters related code and auto-splits any community that grows past 25% of the graph.
- ✓Export the graph as GraphML, Neo4j Cypher, an Obsidian vault with wikilinks, or static SVG.
Getting Started with Installation
Run pip install code-review-graph (or pipx install code-review-graph), then code-review-graph install to auto-detect your AI coding tools — Claude Code, Cursor, Codex, Gemini CLI, Windsurf, Zed, Continue, OpenCode, Copilot, and others — and write the right MCP config for each, or target one directly with --platform <name>. Requires Python 3.10+; installing uv first lets the MCP config use uvx instead of falling back to the bare command. code-review-graph build parses the codebase, and code-review-graph uninstall --dry-run previews a symmetric removal before you commit to it.
Using the CLI and Integrations
After install and build, ask your assistant directly — the README's example is 'Build the code review graph for this project' — or run the three bundled slash commands: /code-review-graph:build-graph, /code-review-graph:review-delta for changes since the last commit, and /code-review-graph:review-pr for a full blast-radius PR review. The CLI itself exposes update for incremental re-indexing, status for graph stats, watch for continuous updates on save, and visualize --format json|graphml|svg to export the graph outside the tool.
Strengths
- ✓Incremental re-indexing is fast enough to run on every save — about 2.5 seconds for a two-file change on a 3,000-file project — instead of a full rebuild.
- ✓Local SQLite storage and no external service call for the graph build mean the CI Action can run entirely on the runner, with the README stating no source code is sent externally.
- ✓The blast-radius benchmark table gives real, reproducible numbers (68.1x on this repo's own corpus, up to 375.6x on fastapi) instead of a marketing claim.
- ✓Custom languages plug in via a languages.toml file with no fork or code change required.
Acknowledged Limitations and Weaknesses
- △The impact-analysis recall of 1.0 the README reports is graph-derived and circular by construction — the ground truth comes from the same edges the predictor walks — and the honest co-change mode that would validate it against real git history currently returns zero predicted files on every graded commit, per the README's own admission.
- △Keyword search, while for most queries the right answer is found within the top 4, has an MRR of 0.35; additionally, the README notes indicate that express queries yield zero hits due to its module-pattern naming.
- △Flow detection recall is 33%, and the README says JavaScript and Go entry-point detection specifically needs work.
- △For small single-file edits, the graph context response can be larger than just reading the changed file, since it carries impact-radius edges and snippets on top of the diff.
Alternatives for AI Code Context Optimization
Common Questions
code-review-graph parses a long list including Python, JavaScript/TypeScript/TSX, Go, Rust, Java, C/C++, C#, VB.NET, Ruby, Kotlin, Swift, PHP, Scala, Solidity, Dart, R, Perl, Lua/Luau, Elixir, Zig, PowerShell, Julia, and more, plus Jupyter/Databricks notebooks — with a languages.toml file to add ones it doesn't cover yet.
It answers questions from a pre-built graph instead of feeding the model whole files: the README's benchmark shows this repo's own 208,821 source tokens becoming about 3,190 tokens per question, a 68.1x reduction, with the median across 6 tested repos at roughly 65x.
Yes — a composite GitHub Action runs the same analysis on your CI runner and posts one sticky, risk-scored PR comment per pull request, updated on every push, with an optional fail-on-risk input to gate merges.
code-review-graph is released under the MIT license, the permissive license shown in its GitHub repository metadata — free to use, modify, and redistribute.
No by default — the graph is built and queried locally in SQLite, and the README states the GitHub Action version stays local-first with no source code sent externally. Semantic search is optional and only calls an external embedding endpoint like Gemini or an OpenAI-compatible API if you configure one.
Drop a languages.toml file into .code-review-graph/ mapping the file extension to a grammar bundled in tree_sitter_language_pack, plus the node types for functions, classes, imports, and calls — the generic Tree-sitter walker handles extraction from there with no fork needed.
Best use cases
- •Running the bundled GitHub Action so every pull request gets a risk-scored, blast-radius comment instead of a human skimming a large diff cold.
- •Feeding Claude Code, Cursor, or another MCP client only the files touched by a change during a review session on a large repo.
- •Watch-mode development where the graph updates on save and stays current for the next question you ask your assistant.
- •Exporting the dependency graph to GraphML or an Obsidian vault to explore architecture and coupling outside the CLI.
Who should try it — and who should skip
Reach for code-review-graph if you already run Claude Code, Cursor, Codex, or another MCP-capable assistant against a repo big enough that whole-file context is expensive — the benchmark table backs the token savings with real numbers per repo. Skip it on small projects where an agent reading the whole codebase is already fast, or if you need CI-verified 100% impact recall today: the README is explicit that the honest co-change validation mode isn't producing usable numbers yet.