Code Review Graph — Token-Efficient Codebase Context via MCP
Cut AI token usage substantially on large codebases by giving the AI a structural map instead of letting it read everything. Savings scale with codebase size — marginal on small projects, large on monorepos.
Overview
code-review-graph is an MCP server that uses Tree-sitter to parse your codebase into an AST graph stored in SQLite. When your AI assistant needs context for a task, it queries the graph first — getting only the files in the blast radius of your change — instead of reading every file in the directory.
Token Impact (illustrative — varies by codebase):
| Codebase Type | Pattern |
|---|---|
| Large monorepo (10K+ files) | Biggest savings — graph reads a small fraction of files |
| Mid-size app (1-5K files) | Meaningful reduction on multi-file changes |
| Small project (<200 files) | Little benefit — graph overhead can exceed savings |
Quality angle: scoping the AI to the blast radius reduces noise, which tends to improve review focus. Measure on your own repo rather than relying on a fixed multiplier.
Bootstrap Protocol (opt-in)
When invoked during /plan or standard usage on a mid-to-large project, check whether graph analysis is available before relying on it:
- Step 1: Check if the tool is installed:
Get-Command code-review-graph(Windows) orwhich code-review-graph(macOS/Linux). - Step 2: Check if a
.code-review-graph/directory exists in the workspace. - Step 3: If installed but the index is missing, ask the user before running
code-review-graph build(it scans the whole project). - Step 4: If not installed and the project is large, ask the user: "Would you like to
pip install code-review-graphand build a local map to cut token usage for this project?" Never install or run build without confirmation.
When to Use vs When to Skip
✅ Install it if:
- Codebase is 500+ files
- You make multi-file changes with cross-module dependencies
- You spend $20+/month on AI assistant tokens
- You work with monorepos, microservices, or cross-package TypeScript
- You want better review quality in addition to cost savings
❌ Skip it if:
- Codebase is under ~200 files with isolated single-file changes
- Heavy use of dynamic patterns (reflection, runtime code gen, dynamic imports)
- You want zero-maintenance — the graph needs to stay in sync
- Team hasn't standardized on an AI coding tool yet
⚠️ Evaluate first if:
- Codebase is 200–500 files — benchmark before committing
- Mix of static and dynamic patterns — test on representative commits
How It Works (4 Layers)
Layer 1: PARSE → Tree-sitter builds ASTs from 19 languages Layer 2: STORE → Nodes + edges saved in SQLite graph Layer 3: TRACE → BFS computes blast radius of changes Layer 4: SERVE → MCP exposes graph to AI assistants
What the Graph Contains
- Nodes: Files, functions, methods, classes, imports, tests
- Edges: "A calls B", "X imports Y", "TestZ covers FunctionW", "ClassA extends ClassB"
- Metadata: Name, type, file path, line range per node
- Privacy: Structural metadata only — NO source code content in the graph
Supported Languages (19)
Python, TypeScript, JavaScript, Go, Rust, Java, C#, Ruby, Kotlin, Swift, PHP, C/C++, Vue SFC, Solidity, Dart, R, Perl, Lua, Jupyter/Databricks notebooks.
Installation
Prerequisites
- Python 3.9+ (
python3 --version) - pip or pipx installed
- An MCP-compatible AI client (AG Kit, Claude Code, Cursor, Windsurf, Zed)
- Git-tracked codebase (for incremental updates)
Step 1: Install the Package
bash# Recommended: isolated environment pipx install code-review-graph # Alternative: fastest, no permanent install uvx code-review-graph install # Alternative: global pip pip install code-review-graph
Step 2: Configure MCP Client
bash# Auto-detect all supported tools code-review-graph install # Or target a specific platform code-review-graph install --platform claude-code code-review-graph install --platform cursor code-review-graph install --platform windsurf
Restart your editor after this step. The MCP server activates on restart.
Step 3: Build the Initial Graph
bashcd /your/project code-review-graph build
| Codebase Size | Expected Build Time |
|---|---|
| 500 files | 10–30 seconds |
| 5,000 files | 2–5 minutes |
| 27,000 files | 5–10 minutes |
Step 4: Enable Watch Mode (Recommended)
bash# Keep graph current as you work code-review-graph watch
Incremental updates complete in under 2 seconds. If you prefer manual updates:
bashcode-review-graph update
Step 5: Verify Integration
Open your AI client and check MCP connection. For Claude Code: run /mcp and confirm code-review-graph appears.
Configuration
Ignore File
Create .code-review-graphignore at project root (uses .gitignore syntax):
# Build artifacts dist/** .next/** build/** # Dependencies node_modules/** vendor/** # Generated files generated/** *.generated.ts *.min.js # Test fixtures (if large) __fixtures__/**
Excluding generated files and build artifacts is critical — they inflate the graph with meaningless nodes.
Multi-Repo Setup
For microservice architectures:
bash# Register additional repos code-review-graph register /path/to/other/repo # List all registered repos code-review-graph repos
The MCP server serves context across all registered repositories.
Core Workflows
1. Blast Radius Analysis (Primary Use)
This is automatic when the MCP server is active. Your AI assistant queries the graph before reading files, getting only the impacted files instead of everything.
Without graph: Changed auth/middleware.py → AI reads 200+ files → 8,200 tokens With graph: Changed auth/middleware.py → Graph returns 12 impacted files → 1,000 tokens
2. Risk-Scored Change Analysis
bashcode-review-graph detect-changes
Scores each uncommitted change by risk level:
- Number of dependents
- Test coverage gaps
- Whether changed functions are on critical paths
- High-risk changes flagged before you ask for review
3. Dead Code Detection
The graph finds nodes with no incoming edges — no callers, no importers, no test coverage:
bash# Surfaces functions/classes that are candidates for removal # Useful on mature codebases to reduce cruft
4. Refactoring Preview
bashcode-review-graph rename preview --from OldClassName --to NewClassName
Shows every file affected by a rename, and flags edge cases (dynamic string references that static analysis can't catch).
5. Architecture Visualization
bashcode-review-graph visualize
Generates interactive visualization showing module clusters using community detection (Leiden algorithm). Useful for:
- Onboarding new contributors
- Identifying architectural drift
- Spotting overly-coupled modules
6. Wiki Generation
bashcode-review-graph wiki
Generates markdown wiki of codebase structure — every module, its public API, dependencies, and test coverage.
Known Limitations
| Limitation | Impact | Mitigation |
|---|---|---|
Dynamic imports (require(variable), import(buildPath())) | Dependencies invisible to parser | Manually note in .code-review-graphignore or accept over-prediction |
Reflection-based calls (Django signals, getattr(), Java reflection) | Missed edges in graph | Serena (LSP-based) is better for these codebases |
Runtime-generated code (eval, template engines) | Not parseable at static time | Accept limitation or exclude from graph |
| Cross-language boundaries (Python calling TypeScript API) | No edges between language runtimes | Use multi-repo registration as partial workaround |
| Stale graph (without watch mode) | Claude queries outdated relationships | Always run code-review-graph update before tasks, or use watch mode |
TypeScript path aliases (@/components/...) | May require tsconfig resolution config | Check tsconfig_resolver.py handles your setup |
Alternatives Comparison
| Tool | Approach | Pros | Cons | Best For |
|---|---|---|---|---|
| code-review-graph | Tree-sitter + SQLite | Fast, 19 languages, local, no deps | Static analysis only | General use, large codebases |
| Claudette | Go rewrite | Single binary, no Python | Fewer languages, simpler | Python-averse teams |
| Serena | LSP-based | Deep semantic precision, type resolution | Heavy setup, slower | Polymorphism-heavy codebases |
| code-graph-rag | RAG + vector search | Natural language queries | Complex setup | Codebase exploration |
| Native IDE context | Editor built-in | Zero setup | No explicit blast radius | Simple projects |
Integration with AG Kit
Complementary Skills
| AG Kit Skill | How It Complements |
|---|---|
context-compression | Graph reduces input context; compression reduces output verbosity |
coordinator-mode | Graph-aware workers can be dispatched with precise file lists |
verify-changes | After graph-informed review, verify changes via execution |
batch-operations | Graph's blast radius informs which files need batch updates |
Recommended Session Architecture
1. Start fresh session for each distinct task 2. Graph pre-filters context → AI reads only blast radius 3. Context compression summarizes completed phases 4. Memory system saves key decisions for next session 5. Result: minimum tokens, maximum quality
Best Practices
- Always run watch mode in development — stale graphs produce stale context
- Exclude generated files — they inflate the graph with noise
- Benchmark first — measure token usage for 1 week without, 1 week with
- Combine with output constraints — graph reduces input, prompt engineering reduces output
- Use
.code-review-graphignorefor build artifacts,node_modules,dist/ - Keep sessions short — fresh sessions + graph = optimal token efficiency
- Multi-repo registration for microservice architectures
