你们有没有这种感觉——让 Claude Code 去看一个 5 万行代码的仓库，它就开始不停地 grep、glob、ls、Read，一次探索任务下来可能花掉一分半钟，工具调用了五六十次，上下文塞满了碎片化的代码片段。
我自己遇到这种情况的时候经常在想：Claude Code 作为一个 AI，真的需要在每次探索代码时重新扫描一遍所有文件吗？它不是应该更聪明一点吗？
CodeGraph 就是来回答这个问题的。
CodeGraph 本质上是一个预索引的代码知识图谱，专门为 Claude Code 的 Explore Agent 设计。它用 tree-sitter 把你的代码库解析成 AST，提取函数、类、变量、调用关系这些符号信息，存进一个本地 SQLite 数据库。
然后 Claude Code 的 Explore Agent 不再需要自己去 grep 文件，而是直接问 CodeGraph："`auth` 这个函数在哪里定义？被哪些地方调用了？它的调用链有多深？"
项目作者在 6 个真实代码库上做了对比测试，有 CodeGraph 和没有 CodeGraph 的差别非常明显：
| 代码库 | 技术栈 | 无 CodeGraph | 有 CodeGraph | 改善幅度 |
|---|---|---|---|---|
| VS Code | TypeScript | 52次调用 / 1分37秒 | 3次调用 / 17秒 | 94%↓调用 / 82%快 |
| Excalidraw | TypeScript | 47次调用 / 1分45秒 | 3次调用 / 29秒 | 94%↓调用 / 72%快 |
| Claude Code | Python+Rust | 40次调用 / 1分8秒 | 3次调用 / 39秒 | 93%↓调用 / 43%快 |
| Claude Code | Java | 26次调用 / 1分22秒 | 1次调用 / 19秒 | 96%↓调用 / 77%快 |
| Alamofire | Swift | 32次调用 / 1分39秒 | 3次调用 / 22秒 | 91%↓调用 / 78%快 |
| Swift Compiler | Swift/C++ | 37次调用 / 2分8秒 | 6次调用 / 35秒 | 84%↓调用 / 73%快 |
CodeGraph 整个流程分成四个阶段：
用 tree-sitter 把源码解析成 AST，然后跑语言特定的查询脚本，提取节点（函数、类、方法）和边（调用、import、继承、实现）。tree-sitter 这套方案的好处是支持的语言多，而且精度比正则高很多。
所有数据存进本地 SQLite 数据库（.codegraph/codegraph.db），搭配 FTS5 全文搜索引擎。数据完全在本地，不走任何外部 API，不需要任何 API key。
这一步做引用消解：函数调用对应到定义处，import 对应到源文件，类继承关系也一并建立起来。还有框架级别的感知——CodeGraph 会识别 Django 的 urls.py、Express 的路由、Spring 的 @GetMapping 这些模式，把 URL 和处理函数链接起来。
MCP 服务器监听文件系统变化，用防抖机制（2 秒静默窗口）过滤噪音，增量同步图谱。只要代码变了，图谱就自动更新。
我特别感兴趣的是跨语言查询。测试中 Claude Code 的 Python+Rust 混合代码库里，问一个跨越两种语言的问题，CodeGraph 的图遍历能跨语言找到关联——这比我预期的要聪明一些。
项目提供交互式安装器，体验不错：
npx @colbymchenry/codegraph安装程序会完成以下步骤：
codegraph CLI~/.claude.json~/.claude/CLAUDE.md--index 同时建立索引）手动安装：
npm install -g @colbymchenry/codegraph在 ~/.claude.json 中添加：
{
"mcpServers": {
"codegraph": {
"type": "stdio",
"command": "codegraph",
"args": ["serve", "--mcp"]
}
}
}cd your-project
codegraph init -iCodeGraph 作为 MCP 服务器提供了 8 个工具：
| 工具名称 | 功能 |
|---|---|
codegraph_search | 按名称在代码库中查找符号 |
codegraph_context | 为任务构建相关代码上下文 |
codegraph_callers | 查找谁调用了某函数 |
codegraph_callees | 查找某函数调用了什么 |
codegraph_impact | 分析修改某符号时影响的代码 |
codegraph_node | 获取特定符号的详细信息 |
codegraph_files | 获取已索引的文件结构 |
codegraph_status | 检查索引健康度和统计 |
codegraph_explore 或 codegraph_context——这两个工具返回大量源码，会把主会话上下文塞满这条规则初看有点反直觉，但仔细想想是合理的：主会话用来做决策和编辑，探索行为交给子 agent，图谱查询结果在那里返回不会污染主上下文。
CodeGraph 还提供 JavaScript/TypeScript 库 API，适合在脚本里调用：
import CodeGraph from '@colbymchenry/codegraph';
const cg = await CodeGraph.init('/path/to/project');
await cg.indexAll({ onProgress: (p) => console.log(`${p.phase}: ${p.current}/${p.total}`) });
const results = cg.searchNodes('UserService');
const callers = cg.getCallers(results[0].node.id);
const context = await cg.buildContext('fix login bug', { maxNodes: 20, includeCode: true });
const impact = cg.getImpactRadius(results[0].node.id, 2);
cg.watch(); // 文件变更时自动同步
cg.unwatch(); // 停止监视
cg.close();affected 子命令能找到某个文件改动会影响到哪些测试，在大型 monorepo 里特别有用：
# 从 git diff 管道输入，只跑受影响的测试
git diff --name-only HEAD | codegraph affected --stdin# CI 集成示例
AFFECTED=$(git diff --name-only HEAD | codegraph affected --stdin --quiet)
if [ -n "$AFFECTED" ]; then
npx vitest run $AFFECTED
fiCodeGraph 的定位很有意思——它不是在替代 Claude Code，而是在优化 Claude Code 的内部行为。同一赛道里还有几个相关项目，但解决的问题各不相同：
| 项目 | 解决的问题 | 定位 |
|---|---|---|
| CodeGraph | Claude Code 探索代码慢、token 浪费 | 代码结构知识图谱 |
| agentmemory | AI Agent 的跨会话记忆 | 会话记忆层 |
| mattpocock/skills | AI 编程的工程纪律 | 技能和流程规范 |
| addyosmani/agent-skills | AI 编程的工程规范 | Google 工程实践 |
这几个项目其实是互补关系，不冲突。CodeGraph 解决"AI 读代码"的问题，agentmemory 解决"AI 记住对话"的问题，mattpocock/skills 解决"AI 编程行为规范"的问题。
91-96% 工具调用减少的数字是项目方自己测的，在更大或更特殊的代码库上能不能复现，需要等社区反馈。
才 3k Stars，246 Forks，14 个 open issues，1 个 release。质量稳定性需要时间验证。不过 tree-sitter 解析代码本身是成熟方案，翻车的概率应该不大。
CodeGraph 默认用原生模块，在没有 C 编译工具链的环境下会回退到 WASM（慢 5-10 倍）。README 里给了各平台安装 build-essential 的命令，但这一步对非技术用户来说可能是个门槛。
Cursor、Cline、Copilot 用户暂时用不了。不过 MCP 协议是通用的，期待未来能扩展。
说到底，CodeGraph 解决的是一个很具体的问题：Claude Code 在大型代码库里探索时太"努力"了，不停地读文件找东西。预索引知识图谱是个聪明的解法，把 AI 变成"查字典"而不是"翻书"。
数字是挺好看的：92% 更少的工具调用，71% 速度提升，19 种语言，13 个框架。但我最想验证的是两点：跨语言查询在真实项目里是不是真的无缝，以及 Auto-Sync 在大型 monorepo 里增量更新会不会卡。
如果你是 Claude Code 的重度用户，手头有 5 万行以上的代码库，值得装上试试——安装过程不复杂，npx @colbymchenry/codegraph 一条命令就完事了。不满意的话 codegraph uninit 也很快。
如果你用 Claude Code 主要处理几千行的小项目，这个工具的边际收益可能没那么明显。
npm install -g @colbymchenry/codegraph