CodeGraph 让 Claude Code Token 暴降 94%：本地代码知识图谱

原文链接：https://mp.weixin.qq.com/s/fsJ0E8pebxxQzylcb1-HdA 来源：ColaAI，2026-05-23

摘要

CodeGraph — 16K Star 开源工具，给 Claude Code 造了一个本地代码知识图谱，替代 Explore Agent 的 grep→ls→Read 暴力遍历模式。平均减少 92% 工具调用、提速 71%、token 消耗降 94%（VS Code 实测从 52 次调用 8.94 万 token 降到 3 次调用 5.66 万 token）。一条 npx 命令安装，tree-sitter 解析 + SQLite FTS5 存储 + MCP 协议接入 + 原生 OS 文件监听自动同步。

核心问题：Claude Code 为什么烧 Token？

Explore Agent 的工作方式：grep 找关键词 → ls 看目录 → Read 几个文件 → 再 grep → 再 Read……

每一次工具调用都在消耗 token。大项目里光找到该看哪几个文件就要几十次调用。

核心洞察： 代码结构在文件保存时就确定了，为什么要每次问问题都重新探索？预先解析好存成图，用的时候直接查。

四层技术架构

层	技术选型	为什么这样选
代码解析	tree-sitter（增量 AST 解析器）	不用 LLM 解析 → 不幻觉、零 token 消耗
存储	SQLite + FTS5 全文索引	不用向量数据库 → 不需要 embedding、零网络
接入	MCP 协议暴露 8 个工具	Claude Code 直接查图谱而非文件系统
同步	FSEvents/inotify/ReadDirectoryChangesW	改代码 2 秒后增量更新，零配置

四个选择都很朴素，但每一个都在避开常见的坑。 纯本地、装完即用。

实测数据

项目	规模	有 CodeGraph	没 CodeGraph	节省
VS Code (TS)	4002 文件	3 次调用 / 17 秒 / 5.66 万 token	52 次调用 / 97 秒 / 8.94 万 token	调用-94%，提速 82%
Swift 编译器	25874 文件 / 27.3 万节点	6 次调用 / 35 秒 / 7.74 万 token	37 次调用 / 128 秒 / 9.91 万 token	调用-84%，提速 73%
Alamofire (Swift)	跨 9 层调用链	3 次调用，深度 3 图遍历，9 步完整调用链	—	grep 做不到的结构化遍历

关键细节：有 CodeGraph 的实验里，agent 一次都没有回头去读文件。 图谱返回的源码片段信息密度已经足够模型做判断。

8 个 MCP 工具

• codegraph_search — 按名字查符号，比 grep 快 10 倍以上
• codegraph_context — 自动构建相关代码上下文，替代 Explore Agent 的核心武器
• codegraph_callers — 谁在调这个函数？重构前必查
• codegraph_callees — 这个函数又调了谁？理解方法内部依赖
• codegraph_impact — 影响半径分析，改公共 API 前的安全网（作者最常用）
• codegraph_node — 单个符号全部信息（位置/源码/文档）
• codegraph_files — 项目文件结构，比 ls 递归快得多
• codegraph_status — 索引健康度检查

安装：一条命令

npx @colbymchenry/codegraph
# 交互式安装器自动完成 4 件事：
# 1. 全局安装 CLI
# 2. 写入 ~/.claude.json MCP 配置
# 3. 8 个工具加入自动授权白名单
# 4. 写入 ~/.claude/CLAUDE.md 全局指令

cd your-project
codegraph init -i

实测感受

🟢 亮点：

• 索引快得离谱（3 万行 Go 项目 10 秒，4000 文件项目 30 秒级）
• 自动同步不用操心，改代码/切分支/git pull 后台默默更新
• 跨语言项目稳定（Vue + Python 前后端调用关系都能追）
• 纯本地，零上传零 API key 零额外延迟

🔴 注意：

• 只对 Claude Code 生效，不用 Cursor/Windsurf 的暂时不适合
• 500 行以下小项目收益不明显，5000 行以上才值得装
• Python 动态调用（getattr/装饰器/metaclass）和 JS 运行时绑定捕捉不到
• 新语言支持有先后，Elixir/Zig/Erlang 等小众语言需等待

安装决策矩阵

✅ 强烈建议装	⏸️ 可以再观望
项目 5000 行以上	小项目个人 demo 居多
经常用 Claude Code 做跨文件探索	主用 Cursor/Copilot
接手陌生代码库很多	代码主要靠运行时动态绑定
在意 token 消耗成本	团队还没接受 MCP 生态

判断标准： 符合"建议装"里任意两条就直接装，安装成本几乎为零，卸载也干净（codegraph uninit）。

更大的趋势

给 AI agent 准备好"预消化"过的上下文，正在变成一个独立的工程方向。代码知识图谱、文档语义索引、个人知识库的 MCP 化——这条路径未来一两年会出现更多类似工具。CodeGraph 是这条路径上一个完成度很高的样本。

让 agent 少做"探索"的功课，多做"判断"的功课。这才是把大模型用对的方式。

• 项目地址： github.com/colbymchenry/codegraph
• npm： @colbymchenry/codegraph
• 协议： MIT
• 平台： Win/Mac/Linux 全支持