用 Claude Code 写代码的人大概都遇到过这种情况：让它理解一个大项目的代码结构，Explore Agent 要跑一两分钟，期间疯狂调用 grep、find、Read，光 token 就烧掉好几万。

上周我在 GitHub Trending 上看到一个叫 CodeGraph 的工具，作者的思路很直接——既然 Agent 每次都要从头扫描文件来理解代码，那为什么不提前把代码的符号关系建好索引？Agent 查索引就行了，不用再一个文件一个文件地翻。

我在自己的项目上试了试，效果确实明显。记录一下安装过程和踩过的坑。

CodeGraph 是什么

说白了就是一个代码知识图谱生成器。它扫描你的项目代码，提取函数、类、变量之间的调用关系，存到本地的 SQLite 数据库里。然后通过 MCP Server 暴露给 Claude Code，Agent 需要了解代码结构的时候直接查图谱，不用再扫文件。

整个过程 100% 本地，不调任何外部 API，数据不出你的机器。

安装：一行命令搞定

最简单的方式：

npx @colbymchenry/codegraph

这个交互式安装器会帮你做四件事：

1. 全局安装 codegraph（MCP Server 要用）
2. 在 ~/.claude.json 里配置 MCP Server
3. 设置 CodeGraph 工具的自动授权
4. 往 ~/.claude/CLAUDE.md 写入全局指令

装完之后，进到你的项目目录初始化：

cd your-project
codegraph init -i

重启 Claude Code，搞定。

如果你不想用交互式安装器，手动配也行。全局安装：

npm install -g @colbymchenry/codegraph

然后在 ~/.claude.json 里加上 MCP Server 配置：

{
  "mcpServers": {
    "codegraph": {
      "type": "stdio",
      "command": "codegraph",
      "args": ["serve", "--mcp"]
    }
  }
}

实测数据：到底快多少

作者在 6 个真实项目上跑了对比测试，我觉得数据比较有说服力，贴一下：

VS Code 项目（TypeScript，4002 个文件）

• 装了 CodeGraph：3 次工具调用，17 秒完成
• 没装：52 次工具调用，1 分 37 秒
• 结果：工具调用减少 94%，速度快 82%

Excalidraw 项目（TypeScript，626 个文件）

• 装了 CodeGraph：3 次调用，29 秒
• 没装：47 次调用，1 分 45 秒
• 工具调用减少 94%，速度快 72%

Alamofire 项目（Swift，102 个文件）

• 装了 CodeGraph：3 次调用，22 秒
• 没装：32 次调用，1 分 39 秒
• 工具调用减少 91%，速度快 78%

最夸张的是一个 Java 项目，只要 1 次 codegraph_explore 调用就回答了整个问题，耗时 19 秒。没装的话要 26 次调用，跑 1 分 22 秒。

平均下来，工具调用减少 92%，速度快 71%。另外一个容易忽略的好处是 token 消耗——装了 CodeGraph 之后文件读取次数降到 0，Agent 不再需要 Read 文件就能拿到关键代码片段。

它支持什么语言

19 种以上：TypeScript、JavaScript、Python、Go、Rust、Java、C#、PHP、Ruby、C、C++、Swift、Kotlin、Dart、Svelte 等等。基本上主流语言全覆盖了。

还有一个我觉得挺实用的功能——Web 框架路由识别。它能认出 Django、Flask、FastAPI、Express、Laravel、Rails、Spring、Gin 这些框架的路由文件，自动把 URL 路径和处理函数关联起来。你问 Agent"这个接口的处理逻辑在哪"，它能直接定位到对应的 handler。

踩坑记录

说几个我实际用的时候碰到的问题。

坑 1：init 之后要重启 Claude Code

这个文档里写了，但我第一次用的时候没注意。codegraph init -i 跑完之后 MCP Server 不会自动加载，必须重启 Claude Code 才生效。不重启的话 Agent 找不到 codegraph 工具，会退回到老的 grep/Read 模式。

坑 2：大项目首次索引需要时间

小项目几秒钟就建好索引了。但如果你的项目有几千个文件，首次索引要等一会。作者测试过 Swift 编译器的源码——25874 个文件、272898 个节点，索引时间不到 4 分钟。好在后续是增量更新，它用 FSEvents（macOS）/ inotify（Linux）监听文件变化，改了代码会自动同步索引。

坑 3：主会话不要直接调 codegraph_explore

这个比较重要。codegraph_explore 和 codegraph_context 会返回大段源代码，直接在主会话调用会撑爆上下文。正确的做法是只在 Explore Agent（子 agent）里用这两个工具，主会话用轻量的 codegraph_search、codegraph_callers、codegraph_callees 做定向查询。

交互式安装器会自动在 CLAUDE.md 里写好这条规则，但手动安装的话得自己加。

坑 4：node_modules 和构建产物

默认情况下 CodeGraph 会跳过 node_modules、.git、dist 这些目录。但如果你的项目有自定义的构建输出目录，可能需要在 .codegraph/config.json 里配置排除规则，不然索引里会掺进一堆编译后的代码。

工具清单

装完 CodeGraph 之后，Claude Code 多了这些 MCP 工具：

codegraph_search —— 按名字搜索符号，全文检索，很快 codegraph_callers / codegraph_callees —— 追踪调用链，看谁调了这个函数、这个函数又调了谁 codegraph_impact —— 改代码之前看影响范围，改了一个函数会波及哪些地方 codegraph_node —— 查单个符号的详细信息 codegraph_explore —— 给 Explore Agent 用的重型工具，一次调用返回相关源码片段 codegraph_context —— 根据任务描述拉取相关上下文

什么场景下值得装

不是所有项目都需要 CodeGraph。我的判断标准：

文件数超过 100 的项目，装。小脚本、小工具就没必要了，Claude Code 直接扫也很快。如果你经常让 Agent 做"理解整体架构""追踪调用链""评估修改影响"这类探索性任务，装了收益很大。如果你的工作主要是在已知文件里改代码，收益就小一些。

另外，如果你用的是按 token 计费的方案，CodeGraph 能省不少钱。从测试数据看，token 消耗平均降了 20%-30%，对于大项目来说一个月下来不是小数目。

小结

CodeGraph 解决的问题很具体：让 Claude Code 的代码探索从"每次都暴力扫描"变成"查预建索引"。安装配置不复杂，一行命令就能跑起来，支持的语言也够多。

如果你天天用 Claude Code 干活，花 5 分钟装一下试试。效果好不好，看你自己项目的情况，但至少从官方测试数据来看，大项目的收益很明显。

项目地址：https://github.com/colbymchenry/codegraph