Code Review Graph

Definition

Code Review Graph is a local knowledge graph for AI coding tools (Claude Code, Cursor, etc.) that builds a persistent structural map of a codebase. It uses Tree-sitter to parse code into AST nodes and edges, letting AI assistants read only the relevant files instead of the whole codebase. The graph sits in a SQLite database under .code-review-graph/, so it stays on your machine. On reviews it cuts tokens by 8.2× on average. Impact analysis keeps 100% recall and never misses an affected file. Incremental updates finish in under 2 seconds. It parses 19 languages plus Jupyter notebooks, works with eight AI editors, and ships under the MIT license.

Key Metrics

• 8.2× average token reduction on reviews
• Up to 49× fewer tokens on daily coding tasks
• 100% recall on impact analysis
• Under 2 seconds for incremental updates

Installation

pip install code-review-graph  # or: pipx install code-review-graph
code-review-graph install      # auto-detects and configures all supported platforms
code-review-graph build        # parse your codebase

Target specific platform:

code-review-graph install --platform codex   # configure only Codex
code-review-graph install --platform cursor  # configure only Cursor
code-review-graph install --platform claude-code  # configure only Claude Code

Detailed Step-by-Step Installation Guide

Step 1: Check Prerequisites

# Check Python version
python3 --version  # Requires Python 3.10+

# Check pip
pip --version

Step 2: Install code-review-graph

# Basic
pip install code-review-graph

# Or with pipx (recommended)
pipx install code-review-graph

Step 3: Install Optional Dependencies

# Core (required)
pip install code-review-graph

# For embeddings (optional)
pip install code-review-graph[embeddings]

# For community detection (optional)
pip install code-review-graph[communities]

# For wiki generation (optional)
pip install code-review-graph[wiki]

# All dependencies
pip install code-review-graph[all]

Details of each option:

Step 4: Auto-Install for AI Platforms

# Install for all platforms
code-review-graph install

# Or only for Claude Code
code-review-graph install --platform claude-code

# Or for Codex
code-review-graph install --platform codex

# Or for Cursor
code-review-graph install --platform cursor

Step 5: Verify Installation

# Check the CLI
code-review-graph --help

# Check the version
code-review-graph --version

Output:

usage: code-review-graph [-h] [--version] {install,build,update,status,watch,visualize,wiki,detect-changes,register,unregister,repos,eval,serve} ...

positional arguments:
  {install,build,update,status,watch,visualize,wiki,detect-changes,register,unregister,repos,eval,serve}
    install               Install and configure for AI platforms
    build                 Build knowledge graph
    update                Incremental update
    status                Show graph statistics
    watch                 Watch mode for continuous updates
    visualize             Generate interactive visualization
    wiki                  Generate markdown wiki
    detect-changes        Analyze changes with risk scoring
    register              Register a repository
    unregister            Unregister a repository
    repos                 List registered repositories
    eval                  Run evaluation benchmarks
    serve                 Start MCP server

Step 6: Build the Graph for a Project

cd /path/to/your/project

# Build graph
code-review-graph build

# Or incremental update (faster)
code-review-graph update

Directory Structure After Installation

project-root/
├── .code-review-graph/          # Graph database
│   ├── graph.db                 # SQLite database
│   ├── embeddings/              # Vector embeddings (if enabled)
│   └── config.json              # Configuration
├── .code-review-graphignore     # Exclude patterns
└── (other project files)

Advanced Configuration

1. Exclude Patterns

Create a .code-review-graphignore file in the root directory:

# Same syntax as .gitignore

# Generated files
generated/**
*.generated.ts
*.generated.js

# Dependencies
node_modules/
vendor/
.venv/
venv/

# Build outputs
dist/
build/
target/

# Test files (optional - you may want to keep them)
tests/**
*_test.py
*_spec.py

# Documentation
docs/
*.md

2. Configuration in pyproject.toml

[tool.code-review-graph]
# Languages to parse
languages = ["python", "typescript", "javascript"]

# Exclude patterns (override .code-review-graphignore)
exclude = ["node_modules/**", "dist/**"]

# Include patterns
include = ["src/**", "lib/**"]

# Watch mode settings
watch = { debounce = 1.0 }

# Embeddings
embeddings = { provider = "sentence-transformers", model = "all-MiniLM-L6-v2" }

3. Environment Variables

# Custom database path
export CRG_DB_PATH=/custom/path/graph.db

# Parallel workers
export CRG_WORKERS=8

# Log level
export CRG_LOG_LEVEL=DEBUG

Troubleshooting

Error: "command not found"

# Add to PATH
export PATH="$PATH:$HOME/.local/bin"

# Or use the full path
~/.local/bin/code-review-graph --help

Error: Missing tree-sitter language

# Install all languages
code-review-graph install-languages

# Or install a specific language
code-review-graph install-languages --language python

Error: SQLite permission

# Check folder permissions
ls -la .code-review-graph/

# Recreate if needed
rm -rf .code-review-graph/
code-review-graph build

Error: Out of memory with a large repo

# Limit parallel workers
code-review-graph build --workers 2

# Exclude more folders
# Add them to .code-review-graphignore

Error: Embeddings failure

# Use basic mode (no embeddings)
code-review-graph build --no-embeddings

# Or install the right dependencies
pip install code-review-graph[embeddings]

Detailed Usage

Real-World Usage Scenarios

1. Initialize a Graph for a New Project

# Step 1: Register the repository
code-review-graph register /path/to/project

# Step 2: Build the graph
code-review-graph build

# Step 3: Check status
code-review-graph status

Output:

Repository: my-project
Language: Python
Files: 234
Nodes: 1,523
Edges: 4,891
Last updated: 2026-04-13 10:30:00

2. Code Review Before Committing

# View changes
code-review-graph detect-changes

# Or use a slash command in Claude Code
/code-review-graph:review-delta

# Or review a PR
/code-review-graph:review-pr

Output:

Blast Radius: HIGH (affects 12 files)
Files affected:
  - src/auth/login.py (modified)
  - src/auth/validator.py (modified)
  - tests/test_auth.py (test)
  - src/api/middleware.py (dependency)

Risk Score: 7/10
Recommendations:
  - Test authentication flows
  - Check JWT token generation
  - Verify middleware integration

3. Search the Codebase

# Query graph
code-review-graph query "User authentication"

# Semantic search (if embeddings are enabled)
code-review-graph query "login flow" --semantic

4. Incremental Updates

# Manual update
code-review-graph update

# Auto-watch mode
code-review-graph watch

# In Claude Code, edit a file → auto-update

5. Generate Visualization

# Create interactive HTML
code-review-graph visualize

# Open in the browser
open .code-review-graph/visualization.html

6. Generate Wiki

# Create markdown wiki
code-review-graph wiki

# Output goes to .code-review-graph/wiki/

7. Cross-Repo Search

# Register multiple repos
code-review-graph register /repo/backend
code-review-graph register /repo/frontend

# Search across repos
code-review-graph query "auth implementation" --all-repos

CLI Commands in Detail

build

# Fresh build (discards the old graph)
code-review-graph build

# Incremental (keeps the old graph)
code-review-graph build --update

# With custom workers
code-review-graph build --workers 8

# Without embeddings
code-review-graph build --no-embeddings

update

# Incremental update
code-review-graph update

# Update specific files
code-review-graph update src/auth/

status

# View statistics
code-review-graph status

# Verbose
code-review-graph status --verbose

detect-changes

# Detect changes
code-review-graph detect-changes

# With diff
code-review-graph detect-changes --diff

# Since specific commit
code-review-graph detect-changes --since HEAD~5

register/unregister

# Register repo
code-review-graph register /path/to/project

# List repos
code-review-graph repos

# Unregister
code-review-graph unregister <repo-id>

MCP Tools (Used in Claude Code)

Best Practices

1. Run the first build for every new project

   code-review-graph build
   

2. Use watch mode during active development

   code-review-graph watch
   

3. Review before every commit

   code-review-graph detect-changes
   

4. Exclude generated files in .code-review-graphignore

5. Commit .code-review-graph/ to share with the team (if the repo is small)

6. Use embeddings for better semantic search

   pip install code-review-graph[embeddings]
   code-review-graph build --embeddings
   

Comparison with Graphify

How It Works

Repository → AST (Tree-sitter) → Graph (nodes/edges) → MCP Query → AI Context

1. Parse: Repository parsed into AST with Tree-sitter
2. Store: Graph of nodes (functions, classes, imports) and edges (calls, inheritance, test coverage)
3. Query: At review time, compute minimal set of files needed

Benchmarks

Token Efficiency

Impact Accuracy

• Average F1: 0.54
• Precision: 0.38
• Recall: 1.0 (100% - never misses affected files)

Performance

• Search latency: 0.4ms - 1.5ms
• Flow detection: 95-128ms

Features

Core Features

• Blast-radius analysis: Trace every caller, dependent, test affected by change
• Incremental updates: Re-parses only changed files, updates in under 2 seconds
• 19 languages + Jupyter notebooks: Python, TypeScript/TSX, JavaScript, Vue, Go, Rust, Java, Scala, C#, Ruby, Kotlin, Swift, PHP, Solidity, C/C++, Dart, R, Perl, Lua, Jupyter

Advanced Features

• Monorepo support: Large repos - 27,700+ files excluded, only ~15 actually read
• Auto-update hooks: Graph updates on every file edit and git commit
• Semantic search: Optional vector embeddings via sentence-transformers, Google Gemini, MiniMax
• Interactive visualization: D3.js force-directed graph with edge-type toggles
• Local storage: SQLite in .code-review-graph/
• Watch mode: Continuous graph updates
• Execution flows: Trace call chains from entry points
• Community detection: Cluster related code via Leiden algorithm
• Architecture overview: Auto-generated architecture map
• Risk-scored reviews: detect_changes maps diffs to affected functions
• Refactoring tools: Rename preview, dead code detection
• Wiki generation: Auto-generate markdown wiki from communities
• Multi-repo registry: Register and search across multiple repos

Slash Commands

CLI Reference

code-review-graph install              # Auto-detect and configure all platforms
code-review-graph install --platform <name>  # Target specific platform
code-review-graph build                # Parse entire codebase
code-review-graph update               # Incremental update
code-review-graph status               # Graph statistics
code-review-graph watch                # Auto-update on file changes
code-review-graph visualize           # Generate interactive HTML
code-review-graph wiki                 # Generate markdown wiki
code-review-graph detect-changes       # Risk-scored impact analysis
code-review-graph register <path>       # Register repo
code-review-graph unregister <id>      # Remove repo
code-review-graph repos                # List registered repos
code-review-graph eval                 # Run benchmarks
code-review-graph serve                # Start MCP server

MCP Tools (22 total)

Configuration

Exclude Paths

Create .code-review-graphignore:

generated/**
*.generated.ts
vendor/**
node_modules/**

Optional Dependencies

pip install code-review-graph[embeddings]       # sentence-transformers
pip install code-review-graph[google-embeddings] # Google Gemini
pip install code-review-graph[communities]      # igraph
pip install code-review-graph[eval]              # matplotlib
pip install code-review-graph[wiki]              # wiki + LLM summaries
pip install code-review-graph[all]               # All dependencies

Supported Platforms

Codex, Claude Code, Cursor, Windsurf, Zed, Continue, OpenCode, Antigravity

License

MIT

Pros

Cons

When to Use

• Large codebases: When reading the entire codebase is not feasible
• Code reviews: Impact analysis before merging
• Token optimization: Reduce context window usage
• Architecture understanding: Community detection, module structure
• Risk assessment: Prioritize code reviews
• Daily coding: Continuous context with minimal tokens

References:

• tirth8205/code-review-graph
• Website
• Discord

See also: Graphify · Graph Comparison · CodeGraph