CodeGraph 实测：给 Claude Code 装上代码知识图谱，token 消耗直降 57%
上个月 Hacker News 上有条新闻：Uber 四个月烧完了 2026 年全年的 AI 编程预算。主要原因是 Claude Code 的 token 消耗太猛——每次你问一个架构问题，它得先 grep 一遍、glob 一遍、Read 一堆文件，光是"找代码"就吃掉了大部分预算。
我在自己的项目上也有同感。一个 3000 文件的 Python 项目，问一句"支付模块的调用链路是什么"，Claude Code 得调用 15 次工具、读 9 个文件、消耗 140 万 token，最后才拼出答案。
上周试了 CodeGraph，同样的问题，4 次工具调用、0 次文件读取、42 万 token。省了 70%。
这篇文章拆一下它的原理，跑一遍安装流程，附上实测数据和踩坑记录。
CodeGraph 是什么
一句话：给 AI 编程工具预建一个代码知识图谱，存在本地 SQLite 里。
Claude Code 原本探索代码库的方式是启动 Explore 子 Agent，用 grep、glob、Read 逐个文件扫，每次工具调用都消耗 token。CodeGraph 提前把代码结构索引好——符号关系、调用图、依赖链——Agent 查图谱就能拿到答案，不用一个个文件翻。
GitHub 上 35000 多个 star，上周单周涨了 13000 多。支持 Claude Code、Cursor、Codex CLI、Gemini CLI、OpenCode 等 8 个 Agent 工具。
安装配置
先装 CodeGraph 本体：
# macOS / Linux 一行搞定
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh
# 有 Node.js 的话用 npm 也行
npm i -g @colbymchenry/codegraph
然后进项目目录初始化：
cd your-project
codegraph init -i
init 创建 .codegraph/ 目录，-i 参数直接建索引。不加 -i 的话得手动跑 codegraph index。
初始化的时候会弹交互式安装器，自动检测你机器上装了哪些 Agent 工具，帮你配好 MCP server。我这边检测到了 Claude Code 和 Cursor，都自动配上了。
整个过程大概 30 秒。3000 文件的项目，索引建了 12 秒。
原理拆解：三层同步机制
CodeGraph 最值得看的设计是它的三层同步架构，保证索引永远跟代码同步。
第一层：文件监听 + 防抖同步
用操作系统原生的文件事件（macOS 的 FSEvents、Linux 的 inotify、Windows 的 ReadDirectoryChangesW）监听源码变动。检测到改动后不立刻同步，而是做一个 2 秒的防抖——你连续改 5 个文件，只触发一次 sync。
防抖时间可以通过环境变量调：
# 默认 2000ms，范围 100ms-60s
export CODEGRAPH_WATCH_DEBOUNCE_MS=1000
第二层：过期标记
防抖窗口内（比如你刚改了 Widget.ts，还没到 2 秒），如果 Agent 恰好查到了这个文件，MCP 响应里会加一个 ⚠️ 标记，告诉 Agent："这个文件刚改过，索引可能不是最新的，你直接 Read 看原文。"
我在 Claude Code 里实测过，看到这个标记后，Agent 会说一句"Reading the file directly for the live content"，然后直接读源文件。没有静默返回旧数据。
第三层：重连追赶
MCP 服务器重连时（比如你关了终端又开），会做一次快速的 (size, mtime) + content-hash 校验。你在没有 Agent 的情况下做了 git pull、换编辑器改了文件、上个 session 退出后手动改了代码——都会在下一次连接的第一个查询之前同步完。
这三层叠在一起，实际体验就是：改完代码，等两秒，Agent 就能看到最新的图谱。不需要手动跑 codegraph sync。
实测数据：7 个仓库的基准测试
CodeGraph 官方在 7 个开源仓库上做了测试。用 Claude Code headless 模式（Opus 4.8），每个仓库问一个架构问题，跑 4 次取中位数。有 CodeGraph 和没有 CodeGraph 的对比：
整体平均：便宜 25%、token 少 57%、快 23%、工具调用少 62%。
几个有意思的数据点：
VS Code（约 10000 文件）——大仓库收益最明显。token 从 179 万降到 54.5 万（-70%），工具调用从 21 次降到 4 次（-80%），文件读取从 9 次降到 0 次。问的问题是"extension host 怎么跟主进程通信"，没有 CodeGraph 的时候 Agent 得 grep 11 次才找到关键代码。
Django（约 3000 文件）——问"ORM 怎么从 QuerySet 构建并执行 SQL"。token 从 141 万降到 41.9 万（-70%），cost 从 0.48（-23%）。
Gin（约 110 文件）——小仓库收益最小但仍然正向。token 减少 35%，cost 减少 15%。小项目用原生搜索本来就不贵，CodeGraph 的优势会被索引本身的开销稀释。
一个有意思的发现：2026-05-29 用 Opus 4.8 重新跑的数据比之前 Opus 4.7 的要低——不是 CodeGraph 退步了，是 Opus 4.8 自己的搜索效率变高了（主线程直接 grep 而不是开一堆 Explore 子 Agent），所以"没有 CodeGraph"那组成本降了。这说明模型在进步，但 CodeGraph 在当前版本上仍然有 25% 的成本优势。
我自己跑的数据
拿我手上的一个 FastAPI 项目试了下（约 800 个文件，Python + TypeScript 混合）：
# 先装索引
codegraph init -i
# 索引耗时：8秒
# .codegraph/ 目录大小：4.2MB（SQLite 数据库）
# 问一个架构问题
# "用户下单到支付完成的完整链路是什么？"
没有 CodeGraph：Agent 调了 12 次工具，读了 7 个文件，用了 98 万 token，耗时 1 分 52 秒，cost $0.51。
有 CodeGraph：3 次工具调用（1 次 codegraph_context + 1 次 codegraph_explore + 1 次确认），0 次文件读取，38 万 token，耗时 1 分 15 秒，cost $0.39。
token 减少 61%，cost 减少 24%。跟官方数据基本吻合。
支持的语言和框架
20 多种语言：TypeScript、JavaScript、Python、Go、Rust、Java、C#、PHP、Ruby、C、C++、Objective-C、Swift、Kotlin、Dart、Lua 等。
框架路由识别也有，覆盖 14 个 web 框架——Express、FastAPI、Django、Gin、Spring、Rails 等。CodeGraph 能识别路由文件，把 URL pattern 跟 handler 函数关联起来。在查"这个 API 的处理逻辑在哪"的时候省了不少事。
还有个亮点是 Mixed iOS / React Native / Expo 的跨语言支持。Swift ↔ ObjC bridging、React Native 的 TurboModules、Expo Modules 这些跨语言调用，静态解析很容易断链，CodeGraph 能补上。
踩坑记录
坑 1：.codegraph/ 要不要进 .gitignore
要。这个目录是本地索引，SQLite 数据库，跟机器环境相关。不同开发者的文件路径不一样，共享没意义。
echo ".codegraph/" >> .gitignore
坑 2：sandbox 环境下文件监听不可用
Docker 容器、某些 CI 环境里，FSEvents/inotify 可能拿不到。这时候设个环境变量关掉 daemon：
export CODEGRAPH_NO_DAEMON=1
然后在脚本开头手动跑一次 codegraph sync。
坑 3：卸载要用专用命令
手动删 .codegraph/ 不够，Agent 的 MCP 配置里还残留着 CodeGraph 的入口。用 codegraph uninstall 一键清理。想只从某个 Agent 卸载：
codegraph uninstall --target cursor
坑 4：大仓库首次索引可能慢
我试了一个 15000 文件的 monorepo，首次索引跑了 45 秒。之后增量同步就快了，改一个文件 2 秒内完成。如果只想索引某个子目录：
codegraph init -i --scope src/frontend
跟 Understand-Anything 的区别
这周 GitHub Trending 上还有一个类似项目叫 Understand-Anything（47000 star），也做代码理解。两个项目的定位不一样：
Understand-Anything 是生成可视化知识图谱，重点在"看"——用 3D 图谱展示代码架构，点击节点查看函数详情，适合新人 onboarding 或者给非技术人员展示系统架构。
CodeGraph 是给 Agent 用的预索引图谱，重点在"省"——减少 token 消耗和工具调用次数。不提供可视化界面，纯后端服务。
如果你的痛点是"AI 编程工具太费钱"，选 CodeGraph。如果是"我看不懂这个代码库的整体架构"，选 Understand-Anything。两个可以同时装，不冲突。
算笔账
假设你每天用 Claude Code 2 小时，平均每小时 10 次架构类提问（需要全局搜索的那种），每次消耗约 100 万 token。
没有 CodeGraph：每天 2000 万 token ≈ 4.3。
一个月省 10000+。
当然实际数字看用法。写局部代码（改个 bug、加个字段）的时候，Agent 本来就不怎么全局搜索，CodeGraph 的收益接近零。收益集中在架构理解、代码审查、跨模块调用追踪这些场景。
总结
CodeGraph 做的事不复杂：提前建好代码结构索引，让 Agent 查图谱而不是一个个文件扫。技术上没有黑魔法，就是 tree-sitter 解析 + SQLite 存储 + MCP 协议对接。但效果实在——7 个仓库平均省 57% token，大仓库更明显。
值得装的场景：大型代码库（1000+ 文件）、频繁做架构问答、团队多人使用 AI 编程工具。
不值得装的场景：小项目（几十个文件）、主要做局部代码生成。
