code-review-graph

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

code-review-graph

Skill by ara.so — Daily 2026 Skills collection.

code-review-graph

builds a persistent structural map of a codebase using Tree-sitter, stores it in a local SQLite graph, and exposes it to Claude via MCP. Instead of re-reading entire projects on every task, Claude queries the graph and reads only the files in the blast radius of a change — averaging 6.8× fewer tokens on code reviews and up to 49× on daily coding tasks in large monorepos.

由ara.so开发的Skill — 属于Daily 2026 Skills合集。

code-review-graph

使用Tree-sitter为代码库构建持久化结构图谱，将其存储在本地SQLite图谱中，并通过MCP暴露给Claude。Claude无需在每次任务中重新读取整个项目，而是查询图谱并仅读取变更影响范围内的文件——在代码评审中平均减少6.8倍的token使用量，在大型单体仓库的日常编码任务中最多可减少49倍。

Installation

安装

Claude Code Plugin (recommended)

Claude Code 插件（推荐）

bash

claude plugin marketplace add tirth8205/code-review-graph
claude plugin install code-review-graph@code-review-graph

Restart Claude Code after installation.

bash

claude plugin marketplace add tirth8205/code-review-graph
claude plugin install code-review-graph@code-review-graph

安装后重启Claude Code。

pip

pip安装

bash

pip install code-review-graph
code-review-graph install   # registers the MCP server with Claude Code

Requires Python 3.10+ and uv.

bash

pip install code-review-graph
code-review-graph install   # 向Claude Code注册MCP服务器

需要Python 3.10+和uv。

Optional: semantic search support

可选：语义搜索支持

bash

pip install code-review-graph[embeddings]

Enables vector embeddings via

sentence-transformers

for

semantic_search_nodes_tool

bash

pip install code-review-graph[embeddings]

通过

sentence-transformers

启用向量嵌入，支持

semantic_search_nodes_tool

。

Initial Setup

初始设置

After installation, open your project in Claude Code and run:

Build the code review graph for this project

Or use the slash command:

/code-review-graph:build-graph

The first build parses the full codebase (~10 seconds for 500 files). After that, the graph updates incrementally on every file save and git commit (under 2 seconds for a 2,900-file project).

安装完成后，在Claude Code中打开你的项目并运行：

为该项目构建代码评审图谱

或者使用斜杠命令：

/code-review-graph:build-graph

首次构建会解析整个代码库（500个文件约需10秒）。之后，每次文件保存和Git提交时，图谱会进行增量更新（2900个文件的项目耗时不到2秒）。

CLI Reference

CLI 参考

bash

undefined

bash

undefined

Register MCP server with Claude Code

向Claude Code注册MCP服务器

code-review-graph install

Parse entire codebase into the graph (first run)

将整个代码库解析到图谱中（首次运行）

code-review-graph build

Re-parse only changed files (subsequent runs)

仅重新解析变更的文件（后续运行）

code-review-graph update

Show graph statistics: node count, edge count, language breakdown

显示图谱统计信息：节点数、边数、语言分布

code-review-graph status

Auto-update the graph as you save files (continuous watch mode)

文件保存时自动更新图谱（持续监听模式）

code-review-graph watch

Generate an interactive D3.js HTML visualisation of the graph

生成交互式D3.js HTML图谱可视化

code-review-graph visualize

Start the MCP server manually (Claude Code does this automatically)

手动启动MCP服务器（Claude Code会自动执行此操作）

code-review-graph serve

---

code-review-graph serve

---

Slash Commands in Claude Code

Claude Code中的斜杠命令

Command	What it does
`/code-review-graph:build-graph`	Build or rebuild the code graph from scratch
`/code-review-graph:review-delta`	Review changes since the last commit
`/code-review-graph:review-pr`	Full PR review with blast-radius analysis

命令	功能
`/code-review-graph:build-graph`	从头开始构建或重建代码图谱
`/code-review-graph:review-delta`	评审自上次提交以来的变更
`/code-review-graph:review-pr`	包含影响范围分析的完整PR评审

MCP Tools (used automatically by Claude)

MCP工具（Claude自动调用）

Once the graph is built, Claude calls these tools without manual prompting:

Tool	Purpose
`build_or_update_graph_tool`	Build or incrementally update the graph
`get_impact_radius_tool`	Find all files/functions affected by a change
`get_review_context_tool`	Return a token-optimised structural summary for review
`query_graph_tool`	Query callers, callees, tests, imports, inheritance
`semantic_search_nodes_tool`	Search code entities by name or meaning
`embed_graph_tool`	Compute vector embeddings for semantic search
`list_graph_stats_tool`	Graph size and health statistics
`get_docs_section_tool`	Retrieve documentation sections
`find_large_functions_tool`	Find functions/classes over a line-count threshold

图谱构建完成后，Claude会自动调用这些工具，无需手动触发：

工具	用途
`build_or_update_graph_tool`	构建或增量更新图谱
`get_impact_radius_tool`	查找变更影响的所有文件/函数
`get_review_context_tool`	返回经过Token优化的结构摘要用于评审
`query_graph_tool`	查询调用方、被调用方、测试、导入、继承关系
`semantic_search_nodes_tool`	按名称或含义搜索代码实体
`embed_graph_tool`	计算向量嵌入以支持语义搜索
`list_graph_stats_tool`	图谱大小和健康状态统计
`get_docs_section_tool`	检索文档片段
`find_large_functions_tool`	查找超过行数阈值的函数/类

Configuration: Ignoring Paths

配置：忽略路径

Create

.code-review-graphignore

in the repository root:

generated/**
*.generated.ts
vendor/**
node_modules/**
dist/**
__pycache__/**
*.pyc
migrations/**

The graph will skip these paths during build and update.

在仓库根目录创建

.code-review-graphignore

文件：

generated/**
*.generated.ts
vendor/**
node_modules/**
dist/**
__pycache__/**
*.pyc
migrations/**

构建和更新时，图谱会跳过这些路径。

Python API

The graph can be queried programmatically for custom tooling or scripts.

可以通过编程方式查询图谱，用于自定义工具或脚本。

Build and update the graph

构建和更新图谱

python

from code_review_graph import GraphBuilder

builder = GraphBuilder(repo_path="/path/to/your/project")

python

from code_review_graph import GraphBuilder

builder = GraphBuilder(repo_path="/path/to/your/project")

Full build (first time)

完整构建（首次运行）

stats = builder.build() print(f"Nodes: {stats['nodes']}, Edges: {stats['edges']}")

stats = builder.build() print(f"节点数: {stats['nodes']}, 边数: {stats['edges']}")

Incremental update (subsequent runs — only parses changed files)

增量更新（后续运行 — 仅解析变更的文件）

update_stats = builder.update() print(f"Re-parsed: {update_stats['files_updated']} files")

undefined

update_stats = builder.update() print(f"重新解析的文件数: {update_stats['files_updated']}")

undefined

Query the graph

查询图谱

python

from code_review_graph import GraphQuery

query = GraphQuery(repo_path="/path/to/your/project")

python

from code_review_graph import GraphQuery

query = GraphQuery(repo_path="/path/to/your/project")

Find all callers of a function

查找某个函数的所有调用方

callers = query.get_callers("authenticate_user") print(callers)

['api/views.py::login_view', 'tests/test_auth.py::test_login']

Find all callees (functions called by a function)

查找某个函数调用的所有被调用方

callees = query.get_callees("process_payment") print(callees)

Find tests that cover a file

查找覆盖某个文件的测试

tests = query.get_tests_for("payments/processor.py") print(tests)

Get inheritance chain for a class

获取某个类的继承链

parents = query.get_inheritance("AdminUser") print(parents)

['BaseUser', 'PermissionMixin']

undefined

undefined

Blast-radius analysis

影响范围分析

python

from code_review_graph import ImpactAnalyzer

analyzer = ImpactAnalyzer(repo_path="/path/to/your/project")

python

from code_review_graph import ImpactAnalyzer

analyzer = ImpactAnalyzer(repo_path="/path/to/your/project")

What is affected if this file changes?

如果该文件变更，会影响哪些内容？

impact = analyzer.get_impact_radius("auth/models.py") print(impact)

{

"direct_callers": ["api/views.py", "middleware/auth.py"],

"transitive_dependents": ["api/tests/test_views.py", "integration/test_flow.py"],

"test_files": ["tests/test_auth.py"],

"blast_radius_size": 7

}

Multiple changed files (e.g., from a git diff)

多个变更文件（例如来自Git diff）

changed_files = ["auth/models.py", "payments/processor.py"] combined_impact = analyzer.get_impact_radius(changed_files)

undefined

changed_files = ["auth/models.py", "payments/processor.py"] combined_impact = analyzer.get_impact_radius(changed_files)

undefined

Semantic search

语义搜索

python

from code_review_graph import SemanticSearch

python

from code_review_graph import SemanticSearch

Requires: pip install code-review-graph[embeddings]

前提：pip install code-review-graph[embeddings]

search = SemanticSearch(repo_path="/path/to/your/project")

Embed the graph (one-time, cached)

为图谱生成嵌入（一次性操作，结果会被缓存）

search.embed()

Search for code entities by concept

按概念搜索代码实体

results = search.search("rate limiting middleware", top_k=5) for r in results: print(r["node"], r["file"], r["score"])

undefined

results = search.search("rate limiting middleware", top_k=5) for r in results: print(r["node"], r["file"], r["score"])

undefined

Find large functions

查找大型函数

python

from code_review_graph import GraphQuery

query = GraphQuery(repo_path="/path/to/your/project")

python

from code_review_graph import GraphQuery

query = GraphQuery(repo_path="/path/to/your/project")

Find functions/classes over 50 lines (good for refactoring targets)

查找超过50行的函数/类（适合作为重构目标）

large = query.find_large_functions(threshold=50) for item in large: print(f"{item['name']} in {item['file']}: {item['lines']} lines")

---

large = query.find_large_functions(threshold=50) for item in large: print(f"{item['name']} 在 {item['file']} 中: {item['lines']} 行")

---

Common Patterns

常见使用模式

Pattern: Review only what changed in the current branch

模式：仅评审当前分支中的变更

bash

undefined

bash

undefined

In Claude Code, after making changes:

在Claude Code中，完成变更后：

/code-review-graph:review-delta


Claude will:
1. Call `build_or_update_graph_tool` to sync the graph with your edits
2. Call `get_impact_radius_tool` on changed files
3. Call `get_review_context_tool` to get a compact structural summary
4. Review only the relevant ~15 files instead of the full codebase

/code-review-graph:review-delta


Claude会：
1. 调用`build_or_update_graph_tool`将图谱与你的编辑内容同步
2. 调用`get_impact_radius_tool`分析变更文件的影响范围
3. 调用`get_review_context_tool`获取紧凑的结构摘要
4. 仅评审相关的约15个文件，而非整个代码库

Pattern: Continuous watch during development

模式：开发过程中持续监听

bash

undefined

bash

undefined

Terminal 1: keep the graph fresh as you code

终端1：保持图谱随代码编辑实时更新

code-review-graph watch

Terminal 2: your normal development workflow

终端2：正常开发工作流


Any file save triggers an incremental re-parse of only that file and its dependents.


任何文件保存都会触发仅针对该文件及其依赖项的增量重新解析。

Pattern: Pre-commit hook

模式：提交前钩子

bash

undefined

bash

undefined

.git/hooks/pre-commit

#!/bin/sh code-review-graph update


Makes the graph always current before Claude sees a commit.

#!/bin/sh code-review-graph update


确保在Claude看到提交前，图谱始终是最新的。

Pattern: Visualise the dependency graph

模式：可视化依赖图谱

bash

code-review-graph visualize

bash

code-review-graph visualize

Opens an interactive D3.js force-directed graph in your browser

在浏览器中打开交互式D3.js力导向图

Toggle edge types: calls, imports, inheritance, test coverage

切换边类型：调用、导入、继承、测试覆盖

Search nodes by name

按名称搜索节点

undefined

undefined

Pattern: Check graph health

模式：检查图谱健康状态

bash

code-review-graph status

bash

code-review-graph status

Example output:

示例输出：

Graph: .code-review-graph/graph.db

图谱: .code-review-graph/graph.db

Nodes: 4,821 (functions: 2,103 | classes: 487 | files: 312)

节点数: 4,821（函数: 2,103 | 类: 487 | 文件: 312）

Edges: 11,204 (calls: 7,891 | imports: 2,108 | inherits: 205 | tests: 1,000)

边数: 11,204（调用: 7,891 | 导入: 2,108 | 继承: 205 | 测试: 1,000）

Languages: Python (180), TypeScript (98), JavaScript (34)

语言: Python (180), TypeScript (98), JavaScript (34)

Last updated: 2026-03-26 01:22:11 (3 files changed)

最后更新时间: 2026-03-26 01:22:11（3个文件变更）

---

---

Supported Languages

支持的语言

Python, TypeScript, JavaScript, Vue, Go, Rust, Java, C#, Ruby, Kotlin, Swift, PHP, Solidity, C/C++

Each language has full Tree-sitter grammar support for: functions, classes, imports, call sites, inheritance chains, and test detection.

Python、TypeScript、JavaScript、Vue、Go、Rust、Java、C#、Ruby、Kotlin、Swift、PHP、Solidity、C/C++

每种语言都有完整的Tree-sitter语法支持，包括：函数、类、导入、调用点、继承链和测试检测。

Adding a New Language

添加新语言

Edit

code_review_graph/parser.py

python

undefined

编辑

code_review_graph/parser.py

：

python

undefined

1. Add file extension mapping

1. 添加文件扩展名映射

EXTENSION_TO_LANGUAGE = { # ... existing entries ... ".ex": "elixir", ".exs": "elixir", }

EXTENSION_TO_LANGUAGE = { # ... 现有条目 ...

".ex": "elixir",
".exs": "elixir",

}

2. Add AST node type mappings for the new language

2. 为新语言添加AST节点类型映射

_CLASS_TYPES["elixir"] = {"defmodule"} _FUNCTION_TYPES["elixir"] = {"def", "defp"} _IMPORT_TYPES["elixir"] = {"alias", "import", "use", "require"} _CALL_TYPES["elixir"] = {"call"}


Then add a test fixture in `tests/fixtures/elixir/` and open a PR.

---

_CLASS_TYPES["elixir"] = {"defmodule"} _FUNCTION_TYPES["elixir"] = {"def", "defp"} _IMPORT_TYPES["elixir"] = {"alias", "import", "use", "require"} _CALL_TYPES["elixir"] = {"call"}


然后在`tests/fixtures/elixir/`中添加测试用例并提交PR。

---

Where the Graph Is Stored

图谱存储位置

The graph is stored locally in

.code-review-graph/graph.db

(SQLite). There is no external database, no cloud dependency, and no data leaves your machine. Add it to

.gitignore

if you don't want it committed:

bash

echo ".code-review-graph/" >> .gitignore

Or commit it to share the pre-built graph with your team (saves the ~10-second initial build for each developer).

图谱存储在本地的

.code-review-graph/graph.db

（SQLite数据库）中。无需外部数据库、无云依赖，数据不会离开你的设备。如果不希望提交到Git，可将其添加到

.gitignore

：

bash

echo ".code-review-graph/" >> .gitignore

或者提交到Git，与团队共享预构建的图谱（为每位开发者节省约10秒的初始构建时间）。

Troubleshooting

故障排除

Graph is stale / not reflecting recent changes

图谱过时 / 未反映最近的变更

bash

code-review-graph update    # incremental re-parse of changed files

bash

code-review-graph update    # 增量重新解析变更的文件

or, if something seems wrong:

或者，如果出现异常：

code-review-graph build # full rebuild from scratch

undefined

code-review-graph build # 从头开始完整重建

undefined

MCP server not connecting to Claude Code

MCP服务器无法连接到Claude Code

bash

undefined

bash

undefined

Re-register the MCP server

重新注册MCP服务器

code-review-graph install

Verify it's registered

验证是否已注册

claude mcp list


Then restart Claude Code.

claude mcp list


然后重启Claude Code。

uv

not found

找不到

uv

bash

undefined

bash

undefined

Install uv (required by the MCP server runner)

安装uv（MCP服务器运行器所需）

curl -LsSf https://astral.sh/uv/install.sh | sh

or

或

pip install uv

undefined

pip install uv

undefined

Semantic search not working

语义搜索无法工作

bash

undefined

bash

undefined

Install the embeddings extra

安装embeddings扩展

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

Compute embeddings (required once after install)

计算嵌入（安装后需执行一次）

code-review-graph embed # or call embed_graph_tool via Claude

undefined

code-review-graph embed # 或通过Claude调用embed_graph_tool

undefined

A language isn't being parsed

某种语言未被解析

Check that the file extension is in

EXTENSION_TO_LANGUAGE

and the corresponding Tree-sitter grammar is installed. Run

code-review-graph status

to see which languages were detected in your project.

检查文件扩展名是否在

EXTENSION_TO_LANGUAGE

中，且对应的Tree-sitter语法已安装。运行

code-review-graph status

查看项目中检测到的语言。

Build is slow on first run

首次构建速度慢

Expected — Tree-sitter parses every file. A 500-file project takes ~10 seconds. All subsequent

update

calls complete in under 2 seconds because only changed files are re-parsed (detected via SHA-256 hash comparison).

这是正常现象——Tree-sitter会解析所有文件。500个文件的项目约需10秒。所有后续

update

调用耗时不到2秒，因为仅重新解析变更的文件（通过SHA-256哈希比较检测）。

How the Token Reduction Works

Token减少的工作原理

On every review or coding task:

Graph query: Claude calls
```
get_impact_radius_tool
```
with the changed files
Blast-radius tracing: the graph follows call edges, import edges, and test edges to find every affected node
Compact summary:
```
get_review_context_tool
```
returns a 156–207 token structural summary (callers, dependents, test coverage gaps, dependency chains)
Targeted reading: Claude reads only the ~15 files in the blast radius, not the full codebase

In the Next.js monorepo (27,732 files): without the graph Claude reads ~739K tokens; with the graph it reads ~15K tokens — a 49× reduction.

在每次评审或编码任务中：

图谱查询：Claude调用
```
get_impact_radius_tool
```
传入变更文件
影响范围追踪：图谱跟随调用边、导入边和测试边，找到所有受影响的节点
紧凑摘要：
```
get_review_context_tool
```
返回156–207个token的结构摘要（调用方、依赖项、测试覆盖缺口、依赖链）
定向读取：Claude仅读取影响范围内的约15个文件，而非整个代码库

在Next.js单体仓库（27,732个文件）中：不使用图谱时Claude读取约739K token；使用图谱时仅读取约15K token——减少了49倍。