Code-Review-Graph: Optimizing AI Code Reviews with Local-First Code Intelligence

What Changed

AI coding tools frequently re-read extensive portions of a codebase during review tasks, leading to inefficient token usage and potentially diluted context. The code-review-graph project introduces a local-first code intelligence graph that addresses this by creating a persistent, structural map of a repository. This map, built using Tree-sitter, allows AI assistants to receive precise context via the Model Context Protocol (MCP), ensuring they only process the code relevant to a specific change.

The tool integrates with various AI coding platforms, including Codex, Cursor, Claude Code, GitHub Copilot, and others. Its install command automatically detects and configures supported platforms, injecting graph-aware instructions into platform rules and installing native hooks where applicable. This aims to streamline the setup process for developers.

Technical Details

code-review-graph operates by parsing a repository into an Abstract Syntax Tree (AST) using Tree-sitter. This AST is then stored as a graph, where nodes represent code elements like functions, classes, and imports, and edges denote relationships such as calls, inheritance, and test coverage. When a code review is initiated, the graph is queried to determine the minimal set of files an AI assistant needs to analyze.

Central to its functionality is blast-radius analysis. Upon a file change, the graph traces all potential callers, dependents, and tests that could be impacted. This 'blast radius' is then provided to the AI, limiting the review scope to only the affected components rather than the entire project. This mechanism is crucial for reducing the context window required by AI models.

The system supports incremental updates, which are triggered by file saves or commit hooks. It performs SHA-256 hash checks to identify changed files and their dependents, then re-parses only the modified sections. This process allows for rapid updates, with a 2,900-file project re-indexing in under 2 seconds. This incremental approach is particularly beneficial for large monorepos, where the tool can exclude tens of thousands of files from review context, providing a highly focused set of relevant files.

code-review-graph offers broad language coverage, supporting a wide array of languages including Python, JavaScript/TypeScript, Go, Rust, Java, C/C++, C#, Ruby, Kotlin, Swift, PHP, and more. It also includes support for Jupyter and Databricks notebooks. For PHP projects, it provides additional semantic edges for Composer PSR-4 resolution, Blade template references, and Laravel Route/Eloquent relationships when explicit framework imports are present.

Developers can extend language support without forking the repository by adding a languages.toml file to the .code-review-graph/ directory. This configuration maps file extensions to existing Tree-sitter grammars and specifies node types for functions, classes, imports, and calls, allowing the generic Tree-sitter walker to handle extraction.

The tool also provides a GitHub Action for CI/CD integration. This action performs risk-scored PR reviews entirely on the CI runner, maintaining a local-first approach with no source code transmitted to external services. It posts a sticky comment on pull requests, detailing risk-scored functions, affected execution flows, and test gaps, with an optional fail-on-risk input to enforce merge gates.

Benchmark Analysis

Benchmarks conducted across six real repositories demonstrate significant token reduction. The median per-question token reduction was approximately 82x when comparing a whole-corpus baseline against graph queries. In some cases, the reduction reached up to 528x. For large monorepos, the tool excluded over 27,700 files from review context, with only around 15 files actually being read by the AI. This resulted in a 93x reduction in tokens per question for the code-review-graph repository itself, funneling 208,821 source tokens down to approximately 2,495 token graph responses.

The average impact F1 score against graph-derived ground truth was 0.71, indicating a reasonable balance between precision and recall in identifying relevant code for review.

Developer Implications

For developers, code-review-graph offers several key advantages. The primary benefit is a substantial reduction in the token cost associated with AI-powered code reviews. By providing AI assistants with a highly focused context, developers can expect more efficient and potentially faster review cycles. This is particularly impactful for large codebases and monorepos where AI tools often struggle with context overload.

The local-first nature of the tool ensures that sensitive source code remains within the developer's environment or CI runner, addressing potential data privacy and security concerns. The automatic configuration and broad platform support aim to lower the barrier to entry for integrating this context-aware functionality into existing AI coding workflows.

The incremental update mechanism means that the code intelligence graph remains current with minimal overhead, avoiding the need for full re-indexing after every minor change. This contributes to a smoother development experience, as the AI's understanding of the codebase is consistently up-to-date.

The GitHub Action for CI/CD allows for automated, risk-scored PR reviews, providing immediate feedback on potential issues and test gaps directly within the pull request workflow. This can help enforce code quality standards and reduce the manual effort involved in identifying critical review areas.

Bottom Line

code-review-graph presents a robust solution for optimizing AI-driven code reviews by providing precise, context-aware information to AI assistants. Its local-first architecture, incremental updates, and significant token reduction benchmarks make it a compelling tool for developers looking to enhance the efficiency and cost-effectiveness of their AI coding workflows, especially within complex and large-scale projects.