Stop burning tokens. Start reviewing smarter.
Claude Code re-reads your entire codebase on every task. code-review-graph fixes that. It builds a structural map of your code with Tree-sitter, tracks changes incrementally, and gives Claude precise context so it reads only what matters.
pip install code-review-graph
code-review-graph install # auto-detects and configures all supported platforms
code-review-graph build # parse your codebaseOne command sets up everything. install detects which AI coding tools you have and writes the correct MCP configuration for each one. Restart your editor/tool after installing.
To target a specific platform:
code-review-graph install --platform cursor # configure only Cursor
code-review-graph install --platform claude-code # configure only Claude CodeRequires Python 3.10+ and uv.
| Platform | Config file | Auto-detected |
|---|---|---|
| Claude Code | .mcp.json |
Yes |
| Cursor | .cursor/mcp.json |
Yes |
| Windsurf | .windsurf/mcp.json |
Yes |
| Zed | .zed/settings.json |
Yes |
| Continue | .continue/config.json |
Yes |
| OpenCode | .opencode/config.json |
Yes |
Then open your project and ask your AI assistant:
Build the code review graph for this project
The initial build takes ~10 seconds for a 500-file project. After that, the graph updates automatically on every file edit and git commit.
Your repository is parsed into an AST with Tree-sitter, stored as a graph of nodes (functions, classes, imports) and edges (calls, inheritance, test coverage), then queried at review time to compute the minimal set of files Claude needs to read.
Blast-radius analysis
When a file changes, the graph traces every caller, dependent, and test that could be affected. This is the "blast radius" of the change. Claude reads only these files instead of scanning the whole project.
Incremental updates in < 2 seconds
On every git commit or file save, a hook fires. The graph diffs changed files, finds their dependents via SHA-256 hash checks, and re-parses only what changed. A 2,900-file project re-indexes in under 2 seconds.
18 supported languages
Python, TypeScript/TSX, JavaScript, Vue, Go, Rust, Java, Scala, C#, Ruby, Kotlin, Swift, PHP, Solidity, C/C++, Dart, R, Perl
Each language has full Tree-sitter grammar support for functions, classes, imports, call sites, inheritance, and test detection.
All numbers come from the automated evaluation runner against 6 real open-source repositories (13 commits total). Reproduce with code-review-graph eval --all. Raw data in evaluate/reports/summary.md.
Token efficiency: 8.2x average reduction (naive vs graph)
The graph replaces reading entire source files with a compact structural context covering blast radius, dependency chains, and test coverage gaps.
| Repo | Commits | Avg Naive Tokens | Avg Graph Tokens | Reduction |
|---|---|---|---|---|
| express | 2 | 693 | 983 | 0.7x |
| fastapi | 2 | 4,944 | 614 | 8.1x |
| flask | 2 | 44,751 | 4,252 | 9.1x |
| gin | 3 | 21,972 | 1,153 | 16.4x |
| httpx | 2 | 12,044 | 1,728 | 6.9x |
| nextjs | 2 | 9,882 | 1,249 | 8.0x |
| Average | 13 | 8.2x |
Why express shows <1x: For single-file changes in small packages, the graph context (metadata, edges, review guidance) can exceed the raw file size. The graph approach pays off on multi-file changes where it prunes irrelevant code.
Impact accuracy: 100% recall, 0.54 average F1
The blast-radius analysis never misses an actually impacted file (perfect recall). It over-predicts in some cases, which is a conservative trade-off — better to flag too many files than miss a broken dependency.
| Repo | Commits | Avg F1 | Avg Precision | Recall |
|---|---|---|---|---|
| express | 2 | 0.667 | 0.50 | 1.0 |
| fastapi | 2 | 0.584 | 0.42 | 1.0 |
| flask | 2 | 0.475 | 0.34 | 1.0 |
| gin | 3 | 0.429 | 0.29 | 1.0 |
| httpx | 2 | 0.762 | 0.63 | 1.0 |
| nextjs | 2 | 0.331 | 0.20 | 1.0 |
| Average | 13 | 0.54 | 0.38 | 1.0 |
Build performance
| Repo | Files | Nodes | Edges | Flow Detection | Search Latency |
|---|---|---|---|---|---|
| express | 141 | 1,910 | 17,553 | 106ms | 0.7ms |
| fastapi | 1,122 | 6,285 | 27,117 | 128ms | 1.5ms |
| flask | 83 | 1,446 | 7,974 | 95ms | 0.7ms |
| gin | 99 | 1,286 | 16,762 | 111ms | 0.5ms |
| httpx | 60 | 1,253 | 7,896 | 96ms | 0.4ms |
Limitations and known weaknesses
- Small single-file changes: Graph context can exceed naive file reads for trivial edits (see express results above). The overhead is the structural metadata that enables multi-file analysis.
- Search quality (MRR 0.35): Keyword search finds the right result in the top-4 for most queries, but ranking needs improvement. Express queries return 0 hits due to module-pattern naming.
- Flow detection (33% recall): Only reliably detects entry points in Python repos (fastapi, httpx) where framework patterns are recognized. JavaScript and Go flow detection needs work.
- Precision vs recall trade-off: Impact analysis is deliberately conservative. It flags files that might be affected, which means some false positives in large dependency graphs.
Slash commands
| Command | Description |
|---|---|
/code-review-graph:build-graph |
Build or rebuild the code graph |
/code-review-graph:review-delta |
Review changes since last commit |
/code-review-graph:review-pr |
Full PR review with blast-radius analysis |
CLI reference
code-review-graph install # Auto-detect and configure all platforms
code-review-graph install --platform <name> # Target a specific platform
code-review-graph build # Parse entire codebase
code-review-graph update # Incremental update (changed files only)
code-review-graph status # Graph statistics
code-review-graph watch # Auto-update on file changes
code-review-graph visualize # Generate interactive HTML graph
code-review-graph wiki # Generate markdown wiki from communities
code-review-graph detect-changes # Risk-scored change impact analysis
code-review-graph register <path> # Register repo in multi-repo registry
code-review-graph unregister <id> # Remove repo from registry
code-review-graph repos # List registered repositories
code-review-graph eval # Run evaluation benchmarks
code-review-graph serve # Start MCP serverMCP tools
Claude uses these automatically once the graph is built.
| Tool | Description |
|---|---|
build_or_update_graph_tool |
Build or incrementally update the graph |
get_impact_radius_tool |
Blast radius of changed files |
get_review_context_tool |
Token-optimised review context with structural summary |
query_graph_tool |
Callers, callees, tests, imports, inheritance queries |
semantic_search_nodes_tool |
Search code entities by name or meaning |
embed_graph_tool |
Compute vector embeddings for semantic search |
list_graph_stats_tool |
Graph size and health |
get_docs_section_tool |
Retrieve documentation sections |
find_large_functions_tool |
Find functions/classes exceeding a line-count threshold |
list_flows_tool |
List execution flows sorted by criticality |
get_flow_tool |
Get details of a single execution flow |
get_affected_flows_tool |
Find flows affected by changed files |
list_communities_tool |
List detected code communities |
get_community_tool |
Get details of a single community |
get_architecture_overview_tool |
Architecture overview from community structure |
detect_changes_tool |
Risk-scored change impact analysis for code review |
refactor_tool |
Rename preview, dead code detection, suggestions |
apply_refactor_tool |
Apply a previously previewed refactoring |
generate_wiki_tool |
Generate markdown wiki from communities |
get_wiki_page_tool |
Retrieve a specific wiki page |
list_repos_tool |
List registered repositories |
cross_repo_search_tool |
Search across all registered repositories |
MCP Prompts (5 workflow templates):
review_changes, architecture_map, debug_issue, onboard_developer, pre_merge_check
| Feature | Details |
|---|---|
| Incremental updates | Re-parses only changed files. Subsequent updates complete in under 2 seconds. |
| 18 languages | Python, TypeScript/TSX, JavaScript, Vue, Go, Rust, Java, Scala, C#, Ruby, Kotlin, Swift, PHP, Solidity, C/C++, Dart, R, Perl |
| Blast-radius analysis | Shows exactly which functions, classes, and files are affected by any change |
| Auto-update hooks | Graph updates on every file edit and git commit without manual intervention |
| Semantic search | Optional vector embeddings via sentence-transformers, Google Gemini, or MiniMax |
| Interactive visualisation | D3.js force-directed graph with edge-type toggles and search |
| Local storage | SQLite file in .code-review-graph/. No external database, no cloud dependency. |
| Watch mode | Continuous graph updates as you work |
| Execution flows | Trace call chains from entry points, sorted by criticality |
| Community detection | Cluster related code via Leiden algorithm or file grouping |
| Architecture overview | Auto-generated architecture map with coupling warnings |
| Risk-scored reviews | detect_changes maps diffs to affected functions, flows, and test gaps |
| Refactoring tools | Rename preview, dead code detection, community-driven suggestions |
| Wiki generation | Auto-generate markdown wiki from community structure |
| Multi-repo registry | Register multiple repos, search across all of them |
| MCP prompts | 5 workflow templates: review, architecture, debug, onboard, pre-merge |
| Full-text search | FTS5-powered hybrid search combining keyword and vector similarity |
Configuration
To exclude paths from indexing, create a .code-review-graphignore file in your repository root:
generated/**
*.generated.ts
vendor/**
node_modules/**
Optional dependency groups:
pip install code-review-graph[embeddings] # Local vector embeddings (sentence-transformers)
pip install code-review-graph[google-embeddings] # Google Gemini embeddings
pip install code-review-graph[communities] # Community detection (igraph)
pip install code-review-graph[eval] # Evaluation benchmarks (matplotlib)
pip install code-review-graph[wiki] # Wiki generation with LLM summaries (ollama)
pip install code-review-graph[all] # All optional dependenciesgit clone https://github.com/tirth8205/code-review-graph.git
cd code-review-graph
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytestAdding a new language
Edit code_review_graph/parser.py and add your extension to EXTENSION_TO_LANGUAGE along with node type mappings in _CLASS_TYPES, _FUNCTION_TYPES, _IMPORT_TYPES, and _CALL_TYPES. Include a test fixture and open a PR.
MIT. See LICENSE.
pip install code-review-graph && code-review-graph install
Works with Claude Code, Cursor, Windsurf, Zed, Continue, and OpenCode