Token-efficient code review using Tree-sitter AST graphs and MCP. Reduces AI assistant token usage by 6.8–49x by computing blast radius of changes instead of reading entire codebases. Uses SQLite graph database for structural analysis.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Token-efficient code review using Tree-sitter AST graphs and MCP. Reduces AI assistant token usage by 6.8–49x by computing blast radius of changes instead of reading entire codebases. Uses SQLite graph database for structural analysis.
when_to_use
When reviewing code in large codebases (500+ files), when token costs are high, when making multi-file changes with cross-module dependencies, or when working with monorepos. Also for dead code detection, architecture visualization, and refactoring previews. NOT for small projects under 200 files with isolated single-file changes.
effort
medium
Code Review Graph — Token-Efficient Codebase Context via MCP
Reduce AI token usage by 6.8x average (up to 49x on monorepos) by giving the AI a structural map of your codebase instead of letting it read everything.
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:
Codebase Type
Without Graph
With Graph
Reduction
FastAPI (3K files)
138,585 tokens
37,217 tokens
3.7x
httpx
64,666 tokens
14,090 tokens
4.6x
Next.js monorepo (27K files)
739,352 tokens
15,049 tokens
49.1x
Express.js (small)
Less benefit
Graph overhead > savings
~1x
Average across 6 repos
—
—
8.2x
Quality also improves: Graph-assisted reviews score 8.8/10 vs 7.2/10 for naive reviews. Less noise = better signal = more accurate output.
🛑 Auto-Bootstrap Protocol (MANDATORY TOOL USE For AI Agents)
When invoked during /plan or standard usage on a mid-to-large project, proactively check if the user can benefit from graph analysis:
Step 1: You MUST explicitly use your terminal/bash execution tool to run a quick check: Get-Command code-review-graph (Windows) or which code-review-graph (macOS/Linux).
Step 2: Check if .code-review-graph/ directory exists in the workspace.
Step 3: If the exit code is 0 (INSTALLED) but the index does not exist, you MUST use your terminal tool to auto-executecode-review-graph build to proactively optimize your token usage before reading multi-file contexts.
Step 4: If exit code is non-zero (NOT INSTALLED) and the project is large, proactively ask the user: "Would you like me to run pip install code-review-graph to build a local map and optimize your token usage by ~8x for this project?"
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
Excluding generated files and build artifacts is critical — they inflate the graph with meaningless nodes.
Multi-Repo Setup
For microservice architectures:
# 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
code-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:
# Surfaces functions/classes that are candidates for removal# Useful on mature codebases to reduce cruft
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
