Introduction & Getting Started
Relevant source files
The following files were used as context for generating this wiki page:
code-review-graph is a persistent, local-first knowledge graph system designed for token-efficient code reviews. By parsing codebases using Tree-sitter and maintaining a structural graph in SQLite, it provides AI coding tools (such as Claude Code, Cursor, and Zed) with compact, high-precision context. This minimizes the volume of source code an AI must ingest, significantly reducing token consumption while improving the accuracy of impact analysis and architectural overviews.
Sources: CLAUDE.md:5-10, README.zh-CN.md:14-19
The project operates primarily as a Model Context Protocol (MCP) server, exposing over 30 tools and several prompt templates to AI clients. It supports a wide array of languages and environments, including Jupyter notebooks and monorepos, and offers features like semantic search, community detection, and automated wiki generation.
Sources: CLAUDE.md:14-38, code_review_graph/main.py:64-70
Core Architecture & Components
The system is structured into several layers, starting from raw source code parsing to high-level architectural analysis.
System Overview
This diagram illustrates the transformation of source code into structural data and its subsequent exposure through the MCP server.
Sources: CLAUDE.md:14-38, README.zh-CN.md:46-51
Key Components
| Component | Responsibility | Relevant Files |
|---|---|---|
| Parser | Multi-language AST parsing using Tree-sitter and targeted fallbacks. | parser.py, custom_languages.py |
| Graph Store | SQLite-backed storage for nodes (functions, classes) and edges (calls, imports). | graph.py |
| MCP Server | FastMCP server entry point registering 30+ tools and 5 prompts. | main.py |
| Change Detection | Git-based incremental updates and risk-scored impact analysis. | incremental.py, changes.py |
| Embeddings | Vector representation for semantic search via local or cloud providers. | embeddings.py |
Sources: CLAUDE.md:14-38, code_review_graph/main.py:75-430
Installation & Setup
Installation is designed to be automated across various platforms. The primary entry point for setup is the install CLI command.
Getting Started Workflow
The automated installation process detects installed AI tools and configures them to use the code-review-graph MCP server.
Sources: README.zh-CN.md:27-32, code_review_graph/skills.py:44-150
Supported Platforms
The system can automatically configure MCP settings for the following environments:
- IDEs: Cursor, VS Code (Copilot), Zed, Windsurf.
- CLI Tools: Claude Code, Codex, Gemini CLI, Qwen Code.
- Frameworks: Continue, OpenCode, Kiro.
Sources: code_review_graph/skills.py:44-150
Core Workflows
To maintain token efficiency, the project emphasizes a "Minimal First" workflow.
Recommended Tool Usage
- Entry Point: Always start with
get_minimal_context_tool. It provides a high-level overview for approximately 100 tokens. - Detail Levels: Use
detail_level="minimal"for initial queries. Only escalate to"standard"for specific entities needing deep inspection. - Targeted Queries: Prefer
query_graph_toolwith a specific pattern (e.g.,callers_of) over broad listing commands.
Sources: CLAUDE.md:11-12, code_review_graph/prompts.py:23-33
The Build and Update Cycle
Incremental updates ensure that a 2,900-file project can be re-indexed in under 2 seconds by only parsing modified files.
Sources: README.zh-CN.md:57-62, code_review_graph/main.py:90-112
Key MCP Tools
| Tool | Purpose |
|---|---|
get_minimal_context_tool | Ultra-compact task context (~100 tokens). Always call first. |
detect_changes_tool | Risk-scored analysis of git diffs mapping to functions/flows. |
get_impact_radius_tool | Analyzes the blast radius of changes across the dependency graph. |
query_graph_tool | Explores relationships like callers_of, tests_for, or inheritors_of. |
get_architecture_overview_tool | Generates a high-level view based on community coupling. |
Sources: code_review_graph/main.py:155-325, CLAUDE.md:195-215
Summary & Significance
By shifting from a file-based scanning approach to a structural graph-based approach, code-review-graph enables AI assistants to understand complex codebases with surgical precision. This local-first architecture ensures that sensitive structural data remains on the developer's machine while providing a 38x to 528x reduction in token usage for typical review tasks.
Sources: README.zh-CN.md:18-22, CLAUDE.md:5-10