How code-review-graph Cuts Token Usage Up to 82× and Doubles Code Review Quality

Problem

AI coding assistants such as Claude Code or Cursor read the entire repository for each request. In large projects this inflates token usage, misses dependency chains, and loses context after each session restart.

Core principle

code-review-graph parses the local codebase with Tree‑sitter to generate an abstract syntax tree (AST). It extracts nodes (functions, classes, imports, tests, Jupyter cells, components) and edges (calls, inheritance, imports, test coverage, cross‑file coupling) and stores them in a local SQLite file .code-review-graph/graph.db. An MCP server then exposes 30 query tools that AI editors can call to retrieve the smallest relevant file set for a review.

Graph construction

Nodes represent individual code entities; edges capture structural relationships. The graph is persisted locally, so no source code leaves the machine, eliminating data‑leak risk for private repositories.

Blast‑radius analysis

When a function or file changes, the tool performs a five‑step chain:

Identify all changed nodes.

Reverse‑traverse callers to find upstream business code.

Forward‑traverse dependencies to locate downstream modules.

Match test cases that cover the changed logic.

Filter out unrelated files and output the minimal review set.

Example: In a Next.js monorepo with 27,732 files, the native approach reads >730 k tokens, while the graph‑based approach reads only 15 files, achieving a 49× token reduction.

Incremental updates

Instead of full re‑indexing, code-review-graph computes SHA‑256 hashes of files and re‑parses only changed files and their dependent nodes. A 2,900‑file project updates in under 2 seconds, and a watch mode continuously refreshes the graph.

Language support

Supports 30+ languages, including Python, TypeScript/JavaScript, Go, Rust, Java, C/C++, C#, Vue, Svelte, Astro, Scala, Kotlin, Swift, PHP, Solidity, Dart, Shell, Zig, PowerShell, Julia, SQL, Ruby, Perl, Lua, Objective‑C, Elixir, Verilog, Jupyter notebooks, and more.

AI platform compatibility

One‑click MCP configuration works with Claude Code, Cursor, Codex, Gemini CLI, GitHub Copilot (VS Code/CLI), Windsurf, Zed, Continue, OpenCode, Kiro, Antigravity, etc., without manual config files.

Core MCP tools

get_impact_radius_tool

: calculates blast radius. get_review_context_tool: optimizes token context. query_graph_tool: queries callers, inheritance, imports, tests. semantic_search_nodes_tool: semantic vector search. detect_changes_tool: risk scoring and test‑gap detection.

Additional capabilities

Interactive D3.js force‑directed graph visualisation with SVG/GraphML/Cypher export.

Local sentence‑transformers or Gemini/OpenAI vector search.

Multi‑repo daemon crg-daemon for unified management.

Custom ignore file .code-review-graphignore to exclude generated code.

Community detection via Leiden algorithm.

Built‑in eval command for token‑consumption benchmarking.

Performance benchmarks (6 real repositories)

fastapi – native tokens: 4,944; graph tokens: 614; reduction: 8.1×

flask – native tokens: 44,751; graph tokens: 4,252; reduction: 9.1×

gin – native tokens: 21,972; graph tokens: 1,153; reduction: 16.4×

httpx – native tokens: 12,044; graph tokens: 1,728; reduction: 6.9×

nextjs – native tokens: 9,882; graph tokens: 1,249; reduction: 8.0×

express – native tokens: 693; graph tokens: 983; reduction: 0.7× (increase due to graph metadata overhead)

Overall recall is 100 % (no missed files), precision 0.38, average F1 0.71. Small single‑file projects may see a token increase because graph metadata adds overhead.

Limitations

Dynamic language features (Python/JS reflection, decorators, eval, getattr) may be missed.

Semantic search mean reciprocal rank ≈ 0.35; relevant results often appear at rank 4.

Execution‑flow recall ≈ 33 % for complex dynamic frameworks.

Additional maintenance: SQLite file, watch process, MCP config.

Minimal benefit for tiny scripts; token usage can even rise.

Recommended scenarios

Large monorepos (thousands of files) with frequent PR reviews.

High‑frequency code reviews, pre‑merge checks.

Changes to shared utilities, middleware, validation functions.

Onboarding new developers to understand architecture.

Massive refactors, renames, dead‑code removal.

Teams sensitive to AI token costs.

Not recommended

Standalone scripts of a few dozen lines.

One‑off demos or tiny tools without complex call graphs.

Pure documentation or static‑asset changes.

Team adoption guidance

Store the graph locally to satisfy security policies.

Integrate code-review-graph detect-changes into CI/CD for automated risk pre‑checks.

Combine with manual review for dynamic‑language projects.

Use pipx for isolated installation to avoid environment conflicts.

Installation example

# Verify Python version
python --version

# Three installation options (pipx recommended)
# 1. Global pip install
pip install code-review-graph

# 2. Isolated pipx install (preferred)
pipx install code-review-graph

# 3. Fast uv install
uv pip install code-review-graph

# Optional extras
pip install code-review-graph[embeddings]   # vector search
pip install code-review-graph[communities] # community detection
pip install code-review-graph[all]        # full feature set

Project repository

https://github.com/tirth8205/code-review-graph