用 Claude Code 久了，很多人会碰到这种情况：问一个简单的架构问题，比如“这个模块的数据流是怎样的”，它却派出 Explore 子 Agent，grep 关键字、glob 找文件、逐个 Read，再顺着调用链一路追下去。几十次工具调用、一两分钟过去，换来一句本该很快就能给出的回答。
Claude Code 读代码时，有相当一部分 token 花在“找上下文”上，而不是写代码。CodeGraph 解决的就是这一段：提前把代码库的结构解析好存在本地，Agent 要了解项目结构时直接查图谱，不用再翻文件。
这篇适合在中大型仓库里用 Claude Code、Codex CLI、Cursor 等 AI 编程工具的开发者，会讲 CodeGraph 的原理、官方基准数据、安装和自动同步机制，以及容易被忽略的上下文占用问题。
CodeGraph 是怎么让 Claude Code 少翻文件的
CodeGraph 是 GitHub 上的开源项目（colbymchenry/codegraph），截至 2026 年 10 月已超过 7 万 star。它的思路可以概括为一句话：把“了解项目结构”从实时翻文件，变成预先算好、随时可查。
具体做法：
- 用 tree-sitter 把源码解析成语法树，提取节点（函数、类、接口、变量）和边（谁调用谁、谁引用谁、继承关系）；
- 把这些节点和边存进本地 SQLite 数据库，作为代码图谱；
- 通过 MCP server 把图谱查询能力提供给 AI 编程工具，Agent 遇到架构类问题时先查图谱。
整个过程完全在本地进行，官方 README 写明不需要 API key，也不会把数据传到外部服务。
官方基准：Claude Code 工具调用和 token 省多少
CodeGraph 仓库放了一份对比基准：同一个架构问题，用 claude -p 无头模式分别在开启和不开启 CodeGraph MCP 的情况下跑，每组 4 次取中位数。原文引用的是早期版本的数据；仓库在 2026 年 8 月用新版本重新测了一遍，下面以当前 README 为准。
7 个代码库的平均结果：工具调用减少 88%，耗时缩短 53%，处理的 token 减少 62%，成本降低 44%，并且在全部 7 个仓库里文件读取次数都降到了 0。
部分仓库的中位数对比（开启 CodeGraph / 不开启）：
| 代码库 | 规模 | 工具调用 | 耗时 | 处理 token |
|---|---|---|---|---|
| VS Code | TypeScript，约 1.1 万文件 | 2 次 / 28 次 | 58 秒 / 2 分 10 秒 | 155k / 670k |
| Excalidraw | TypeScript | 2 次 / 43 次 | 45 秒 / 2 分 42 秒 | 156k / 991k |
| Tokio | Rust | 3 次 / 29 次 | 1 分 3 秒 / 2 分 43 秒 | 201k / 573k |
| Django | Python | 3 次 / 14 次 | 54 秒 / 1 分 23 秒 | 183k / 309k |
| Gin | Go | 1 次 / 7 次 | 28 秒 / 46 秒 | 87k / 180k |
README 里也说得很清楚：节省多少主要看这个问题需要多少“探索”。原本要几十次工具调用才能答出来的问题，成本能降 57% 到 78%；原本 7 次左右就能找到答案的问题，两边差距就很小。
如果你在排查 Claude Code 额度为什么用得快，可以结合 Claude Code 配额为什么消耗这么快 一起看：缓存过期、后台会话这类因素之外，“找上下文”本身也是一大块开销。
CodeGraph 安装与配置：三步接入 AI 编程工具
原文写的是“一行命令装完”，当前版本把安装拆成了三步，各管一件事：
- 安装 CLI：按仓库 README 提供的官方安装脚本安装（macOS、Linux 和 Windows 各有对应脚本），CLI 自带运行时，不需要另装 Node.js。装完要新开一个终端，
codegraph命令才能生效。 - 接入 Agent：在新终端里运行
codegraph install。它会检测本机装了哪些 AI 编程工具，并为它们配置 CodeGraph 的 MCP server。README 列出的支持对象包括 Claude Code、Cursor、Codex CLI、opencode、Gemini CLI、Kiro、GitHub Copilot 等。这一步只负责接入，不会建索引。 - 建索引：进入项目目录运行
codegraph init，为当前项目建立图谱，索引存在项目下的.codegraph/目录。
已经装了 Node.js 的话，也可以用 npx @colbymchenry/codegraph 一步完成下载和接入。之后升级运行 codegraph upgrade，它会自动识别你当初的安装方式。
卸载的行为也和原文描述的不同：现在 codegraph uninstall 会移除各个 Agent 里的 MCP 配置，同时卸载 CLI 本身；只想去掉 Agent 配置、保留 CLI，就加 --keep-cli。项目里的 .codegraph/ 索引不会被删，需要的话在对应项目里运行 codegraph uninit 单独清理。
改代码后图谱怎么保持同步
CodeGraph 默认开启自动同步，用系统原生的文件监听：macOS 用 FSEvents，Linux 用 inotify，Windows 用 ReadDirectoryChangesW。
- 增量更新：改了哪个文件，就只重新索引那个文件的节点和边，不会全量重建。README 给的数据是，4400 个文件的项目单次同步大约 0.3 秒。
- 防抖窗口：默认 2 秒（可以用环境变量
CODEGRAPH_WATCH_DEBOUNCE_MS调整），连续保存会合并成一次同步，避免边写边重建影响编辑。 - 过期提示：在防抖窗口内，如果查询结果涉及还没同步的文件，返回内容会带一条提示，让 Agent 直接去读那个文件的最新内容。
限制与注意事项
- 上下文占用反而更高：这是 README 主动写出来的一点。CodeGraph 减少的是“处理过的 token”，但它一次返回的结果比较密集，会一直留在上下文窗口里。官方在多轮会话里测到，会话结束时残留的检索上下文比读文件的方式多约 80%（VS Code 上是 67k 对 18k）。上下文窗口小、会话又长的话，要把这部分算进去。
- 小项目收益有限：节省幅度取决于问题需要多少探索。几十个文件的小项目，开不开区别不大。
- 别让子 Agent 绕过图谱：README 提到，CodeGraph 只有被直接查询时才有用；如果模型把探索任务交给会读文件的子 Agent，图谱反而成了额外开销，所以它的指令会引导 Agent 直接回答。
- 它和知识图谱文档工具不是一类：CodeGraph 侧重给 Agent 提供结构查询。想对比代码图谱和仓库文档两类工具的用途，可以看 GitNexus 与 DeepWiki 怎么选。
总结
CodeGraph 把 Claude Code 最耗时的“找上下文”环节换成了本地图谱查询：仓库越大、问题越需要探索，省下的工具调用、时间和费用就越明显。安装是三步：装 CLI、codegraph install 接入 Agent、codegraph init 建索引。同时要记住官方提醒的另一面：它会让更多检索内容常驻上下文。
如果你在 AIGoCode 上使用 Claude Code 或 Codex，可以先在一个中大型仓库里装上 CodeGraph，对比一下同一个问题前后的用量。