AI-powered code review tool that cuts token costs by 8.2x
Build semantic knowledge graphs of your codebase for smarter AI code reviews with Claude, Cursor, Gemini CLI, and more
AI coding assistants (Claude Code, Cursor, Gemini CLI) re-read your entire codebase on every review, refactor, or debug task. A 10,000-file monorepo = 10,000 files × N tasks = millions of wasted tokens.
generalized-code-review-graph solves this by building a persistent knowledge graph of your code structure, then giving AI assistants only the minimal context they need via MCP (Model Context Protocol).
- Parse once — generalized-code-review-graph parses your repo using Tree-sitter (19 languages supported)
- Build graph — Stores code structure (functions, classes, imports, calls) in local SQLite
- AI gets context — When you ask for a code review, AI queries the graph instead of reading entire files
- Pay less — AI reads only affected files, parameters, dependencies. Result: 8.2x fewer tokens
pip install generalized-code-review-graph
code-review-graph install # Auto-detects Claude Code, Cursor, Gemini CLI, Windsurf, Zed, etc.
code-review-graph build # Parse your codebase (takes ~10s for 500 files)Open your IDE and ask your AI assistant:
Build the code review graph for this project
Then:
Review my changes and show impact radius
The graph will show:
- ✅ Which functions/classes are affected
- ✅ Which tests will break
- ✅ Code complexity of changed code
- ✅ Documentation gaps
- ✅ Code smells introduced
- 8.2x average cost reduction (benchmarked on 6 real repos)
- Reads only affected files, not entire codebase
- Works with Claude Code, Cursor, Gemini CLI, Windsurf, Zed, Continue, OpenCode, Antigravity
| Feature | What It Does |
|---|---|
| Blast-radius analysis | Shows exactly which functions/tests are affected by changes |
| Code complexity metrics | Cyclomatic complexity, cognitive complexity, nesting depth per function |
| AI readability layer | Extracts docstrings, intent tags (TODO/FIXME), documentation gaps |
| Code smell detection | Automatically flags God objects, long parameter lists, deep nesting, magic numbers |
| Execution flow tracing | Trace call chains from entry points, sorted by criticality |
| Architecture overview | Auto-generated codebase maps with coupling analysis |
- Incremental updates — Changes sync in <2 seconds via git hooks
- 19 languages — Python, TypeScript, JavaScript, Go, Rust, Java, C++, C#, Ruby, Kotlin, Swift, PHP, Solidity, Dart, R, Perl, Lua, Vue, Jupyter notebooks
- Interactive visualization — D3.js force-directed graph with search
- Local storage — SQLite in
.code-review-graph/. No cloud, no API keys, no SaaS lock-in - Multi-repo support — Register multiple repos, search across all of them
- 22 MCP tools — Direct integration with Claude Code, Cursor, Gemini CLI
- 5 workflow prompts — Review changes, architecture map, debug issue, onboard developer, pre-merge check
- Semantic search — Optional vector embeddings (sentence-transformers, Google Gemini, MiniMax)
- Risk-scored reviews —
detect_changesmaps diffs to affected functions, flows, test gaps
Scan of 22 Python files, 147 functions/classes:
| Metric | Value | What It Means |
|---|---|---|
| Functions documented | 89/105 (84.8%) | High quality → fewer surprises |
| Documentation gaps | 5 functions | AI knows exactly which functions need docs |
| Avg complexity | 3.41 | Low complexity → easy to understand |
| Hotspot function | CC=23 | 1 function needs careful review |
| Deep nesting | 2 functions | Very few complex control structures |
| Long param lists | 3 functions | Minimal design issues |
| Intent coverage | 105/105 (100%) | All functions have TODO/FIXME context |
Result: AI assistant reviews this 3,000-line project by reading:
- 5 undocumented functions
- 1 high-complexity function
- 3 parameter design issues
- Intent metadata for all 105 functions
Token savings: 60-80% context window reduction + better accuracy
- Claude Code — Native integration via MCP
- Cursor IDE — Full support with .cursorrules injection
- Gemini CLI — First-class integration with auto-detection
- Windsurf — MCP server auto-configuration
- Zed Editor — LSP-style MCP integration
- Continue.dev — Plug-and-play MCP setup
- OpenCode — Native support
- Antigravity — Standalone MCP server
One command configures all installed tools:
code-review-graph install- Python 3.10+
- Git (for change detection)
- Optional: uv for faster installation
# Via pip (recommended)
pip install code-review-graph
# Via pipx (isolated environment)
pipx install code-review-graph
# Via uv (fastest)
uv pip install code-review-graph# Auto-detect and configure all installed tools
code-review-graph install
# Or target specific platform
code-review-graph install --platform cursor
code-review-graph install --platform claude-code
code-review-graph install --platform gemini-clicode-review-graph build # Full build (one-time, ~10s per 500 files)
code-review-graph update # Incremental update on file changes
code-review-graph status # View graph stats
code-review-graph health # Code quality report| Repository | Files | Avg Naive Tokens | Graph Tokens | Savings |
|---|---|---|---|---|
| express.js | 141 | 693 | 983 | 0.7x |
| fastapi | 1,122 | 4,944 | 614 | 8.1x |
| flask | 83 | 44,751 | 4,252 | 9.1x |
| gin (Go) | 99 | 21,972 | 1,153 | 16.4x |
| httpx | 60 | 12,044 | 1,728 | 6.9x |
| next.js | 2,900+ | 9,882 | 1,249 | 8.0x |
| Average | 2,300+ | — | — | 8.2x |
Naive = reading all files. Graph = reading only affected files. Source:
evaluate/reports/summary.md
| Repo | Recall | Precision | F1 Score |
|---|---|---|---|
| express | 1.0 | 0.50 | 0.667 |
| fastapi | 1.0 | 0.42 | 0.584 |
| flask | 1.0 | 0.34 | 0.475 |
| gin | 1.0 | 0.29 | 0.429 |
| httpx | 1.0 | 0.63 | 0.762 |
| next.js | 1.0 | 0.20 | 0.331 |
| Average | 1.0 | 0.38 | 0.54 |
100% recall = never misses affected files. Conservative precision = flagging extra files is safer.
Problem: Claude Code/Cursor/Gemini CLI reading 100 files = $0.50-2.00 per review
Solution: code-review-graph reads 15 files = $0.06-0.25 per review
Result: 8.2x cheaper code reviews
Problem: 27,000+ files in Next.js monorepo → AI can't focus on relevant code
Solution: Graph identifies ~15 affected files per change
Result: AI understands impact in seconds, not minutes
Problem: New dev doesn't understand architecture → reads entire codebase (weeks)
Solution: Graph shows community structure, execution flows, entry points
Result: Onboarding in hours, not weeks
Problem: No way to detect code smells automatically
Solution: code-review-graph detects God objects, deep nesting, long parameter lists
Result: CI/CD flags design issues before review
Problem: 30% of functions undocumented → no context for AI
Solution: code-review-graph flags documentation_gap for every function
Result: AI says "this function needs docs" during reviews
# Build & Manage
code-review-graph install # Auto-detect and configure all platforms
code-review-graph build # Full rebuild (parse entire repo)
code-review-graph update # Incremental update (changed files only)
code-review-graph watch # Auto-update on file changes
# Query & Analyze
code-review-graph status # Graph statistics
code-review-graph health # Code quality report (complexity, smells, docs)
code-review-graph detect-changes # Risk-scored change analysis
code-review-graph visualize # Generate interactive D3.js graph
# Documentation
code-review-graph wiki # Generate markdown wiki from code structure
# Multi-Repo
code-review-graph register <path> # Register repo in multi-repo registry
code-review-graph repos # List registered repos
code-review-graph unregister <id> # Remove repo from registry
# Evaluation
code-review-graph eval # Run benchmarks on sample repos
code-review-graph serve # Start MCP server (for custom integrations)All MCP tools work automatically in Claude Code, Cursor, Gemini CLI, etc.
| Tool | Purpose |
|---|---|
detect_changes |
Risk-scored analysis of code changes |
get_impact_radius |
Show blast radius of changed files |
get_review_context |
Token-optimized review context |
semantic_search_nodes |
Find code by meaning (vector + keyword) |
query_graph |
Trace callers, callees, tests, imports |
get_architecture_overview |
Codebase structure & coupling analysis |
list_communities |
Code communities (clusters) |
get_community |
Details of a code community |
list_flows |
Execution flows (entry points) |
get_flow |
Details of a single flow |
get_affected_flows |
Which flows are impacted by changes |
get_code_quality_warnings |
Functions above complexity threshold |
get_code_smells |
Flag God objects, long params, deep nesting |
list_undocumented_functions |
Find functions missing documentation |
find_large_functions |
Functions exceeding line count threshold |
refactor_tool |
Rename preview, dead code, suggestions |
apply_refactor_tool |
Apply refactoring changes |
generate_wiki |
Create markdown wiki from structure |
get_wiki_page |
Retrieve wiki for a code community |
list_repos |
List registered repositories |
cross_repo_search |
Search across multiple repos |
build_or_update_graph |
Build/update graph programmatically |
Create .code-review-graphignore in repo root:
generated/**
*.generated.ts
node_modules/**
vendor/**
.git/**
**/__pycache__/**
pip install code-review-graph[embeddings] # Vector search (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[wiki] # Wiki generation with LLM summaries
pip install code-review-graph[eval] # Benchmarking tools
pip install code-review-graph[all] # EverythingA: code-review-graph is free and open source (MIT license). Reduces cost of Claude Code/Cursor by 8.2x by cutting tokens.
A: No. Everything runs locally. SQLite database is in .code-review-graph/ directory. Zero external dependencies.
A: Claude Code, Cursor, Gemini CLI, Windsurf, Zed, Continue, OpenCode, Antigravity. One command configures all.
A: ~10 seconds for 500 files. 2-3 minutes for 10,000 files. Depends on file count and language complexity.
A: No. Incremental updates (via git hooks) take <2 seconds. Full rebuild only needed after major refactors.
A: 19: Python, TypeScript/TSX, JavaScript, Vue, Go, Rust, Java, Scala, C#, Ruby, Kotlin, Swift, PHP, Solidity, C/C++, Dart, R, Perl, Lua, plus Jupyter/Databricks notebooks.
A: Yes. Use code-review-graph register <path> to add repos to a multi-repo registry. Then use cross_repo_search MCP tool.
A: Works the same. Database is local, no cloud upload. Configure normally with SSH/HTTPS credentials you already use.
| Repo | Files | Nodes | Edges | Build Time |
|---|---|---|---|---|
| express | 141 | 1,910 | 17,553 | ~0.2s |
| fastapi | 1,122 | 6,285 | 27,117 | ~0.8s |
| flask | 83 | 1,446 | 7,974 | ~0.1s |
| gin | 99 | 1,286 | 16,762 | ~0.1s |
| httpx | 60 | 1,253 | 7,896 | ~0.05s |
All searches complete in <2ms via SQLite FTS5 + optional vector embeddings.
git clone https://github.com/natkal-coder/code-review-graph.git
cd code-review-graph
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytestEdit code_review_graph/parser.py:
- Add file extension to
EXTENSION_TO_LANGUAGE - Add node type mappings for classes, functions, imports, calls
- Add test fixture in
tests/fixtures/ - Submit PR
- Phase 2: Refactoring suggestions (extract methods, consolidate duplicate code)
- Phase 3: Training data export for code generation models
- Phase 4: IDE plugins (VS Code, JetBrains, Neovim)
- Phase 5: LLM fine-tuning on code graphs (better code understanding)
MIT. See LICENSE.
- Discord: Join us
- GitHub Issues: Report bugs or request features
- GitHub Discussions: Share use cases, ask questions
- Twitter: @natkal_coder
Stop burning tokens. Start reviewing smarter.
pip install code-review-graph && code-review-graph install
Works with Claude Code, Cursor, Gemini CLI, Windsurf, Zed, Continue, OpenCode, and Antigravity