CodeGraph：64.5K Star 的代码知识图谱，7 个月从 0 到 6 万 Star，让 Coding Agent 少打 89% 的工具调用

Agent 读代码的方式，还停留在 1998 年

让 Claude Code 或 Codex 回答一个架构问题——"用户请求是怎么一路走到数据库的？"——它会干什么？grep、glob、Read，一个文件一个文件地翻，自己手工重建调用链和依赖关系。在它真正开始干活之前，先烧掉几十次工具调用和几十万 token。

这不是模型笨，是工具层没有给 Agent 一条捷径。IDE 有人类用的"转到定义"，Agent 只有 grep。

这就是 CodeGraph 要填的坑：把整个代码库预先解析成一张知识图谱——每个符号、每条调用边、每个依赖——存进本地 SQLite。Agent 不再爬文件，而是问一个问题，拿回"正好需要的代码"。

这个项目 2026 年 1 月 18 日才创建，7 个月拿到 64,489 Star。这个速度，在代码智能这个已经卷成红海的赛道里，说明它确实戳中了什么。

它到底是什么

• 64,489 Star，MIT 协议，npm 包 @colbymchenry/codegraph 当前 v1.5.0（2026-07-21 发布，项目仍在高频迭代）
• Rust 原生内核解析 + tree-sitter 语法，20 种语言全量支持，40+ 种语言可解析
• 预索引 + 自动同步：文件一改，图就更新，Agent 永远拿到新鲜索引
• 100% 本地：SQLite 单文件（.codegraph/codegraph.db），FTS5 全文搜索，无 API key、无外部服务
• 8 个 Agent 官方支持：Claude Code、Cursor、Codex CLI、opencode、Hermes Agent、Gemini CLI、Antigravity IDE、Kiro
• 单 MCP 工具设计：整个 MCP surface 默认只暴露一个 codegraph_explore——一次调用返回相关符号的逐字源码（按文件分组）+ 符号间调用路径 + 爆炸半径摘要

一句话：给 Agent 一个"预读过的代码库大脑"，让它从"爬文件"变成"查图谱"。

为什么涨这么快：基准数据是真的

README 里贴了一组 2026-07-21 用 Claude Opus 4.8 在 7 个真实开源代码库（VS Code、Excalidraw、Django、Tokio、OkHttp、Gin、Alamofire）上重测的基准，每个库同一个架构问题、有图 vs 无图、4 次取中位数：

总体：工具调用平均省 89%，成本平均省 60%，Token 平均省 69%，7 个库文件读取全部归零。无图一方最惨的 Tokio 花了 57 次工具调用、430 万 token 去"重新发明"图谱里已有的结构。

两个诚实的小注脚：小库上无图方的 grep 循环偶尔墙钟时间更快（比如 Excalidraw 23s vs 36s），但代价是 5-10 倍的 token 和 4-7 倍的成本；OkHttp 无图方"运气好"5 次调用就答完，有图方 1 次调用但贵了 3 美分。也就是说：省的是 token 和钱，图省不了墙钟时间——这个别被标题党骗了。

最反主流的设计：整个 MCP 只有一个工具

别的代码智能项目（包括我们写过的 code-review-graph、CodeDB）都在堆 MCP 工具数量——21 个、175 个。CodeGraph 反着来：默认只暴露一个 codegraph_explore。

理由是实测的：工具菜单越宽，Agent 越容易选错，而且每个列出的工具都占用会话上下文。其他 7 个工具（codegraph_node、codegraph_search、codegraph_callers、codegraph_callees、codegraph_impact、codegraph_files、codegraph_status）功能完整但默认不列出——它们返回的东西，codegraph_explore 已经内联给你了。想加回来用环境变量 CODEGRAPH_MCP_TOOLS=explore,node,search,callers。

一个工具干所有事，靠的是返回结构：

codegraph_explore "How does a request reach the database?"
→ 相关符号的逐字源码（按文件分组，带行号）
→ 符号之间的调用路径（含 grep 追不上的动态分派跳转）
→ 爆炸半径摘要（改了会波及谁）

MCP server 还会在 initialize 握手时把使用指引直接塞给 Agent：结构性问题直接用 CodeGraph 答、别用 grep 重复验证、改完代码看 staleness 警告。指引还特意警告别把探索工作委托给子 Agent——子 Agent 看不到 MCP 指引，照样去读文件，CodeGraph 就成了纯开销。

怎么实现的：Rust 内核 + 三层保鲜机制

架构不复杂，但每个环节都做了取舍：

• 解析：native Rust 内核把 tree-sitter 语法直接编译进去，20 种语言每种都验证过与参考引擎在图谱上逐字节一致（从小的库到 Linux 内核）。每个文件只跨一次语言边界。平台没有预编译二进制或文件有语法错误时，自动按文件回退到便携引擎，图一样。
• 存储：全部进本地 SQLite（.codegraph/codegraph.db），FTS5 做全文搜索。
• 解析引用：函数调用 → 定义、import → 源文件、继承关系、框架约定模式，全部解析成边。
• 自动同步（三层）：

第 1 层：文件 watcher（FSEvents / inotify / ReadDirectoryChangesW）
        → 文件改动后 2 秒 debounce（可配 CODEGRAPH_WATCH_DEBOUNCE_MS）
        → 增量同步，只重算变了的文件

第 2 层：staleness banner —— debounce 窗口内，MCP 响应里凡是涉及
        还没同步的文件，前置 ⚠️ 警告并提示 Agent 直接 Read。
        实测 Claude Code 会真的说"Reading the file directly for the live content"

第 3 层：连接时补同步 —— MCP server 每次连上先做 (size, mtime) + 内容哈希对账，
        git pull、别的编辑器、上个 Agent 会话留下的改动全部吸收

性能数据：Swift 编译器仓库（27k 文件）全量索引约 100 秒，改一个文件重同步约 4 秒；Linux 内核（70k 文件、200 万符号、640 万关系）在 2 核 / 6GB VPS 上 12 分钟内建完——注意它号称"RAM-first 设计在 1% 前就 OOM"的对比，所以做了容器感知的资源自适应：VPS 给 2 核就按 2 核调度，不按宿主机的 64 核来。

还有个值得一提的：Framework-aware Routes——它能识别 Django、Flask、FastAPI、Express、NestJS、Spring、Gin、Axum、Rails、Laravel 等 17 个 Web 框架的路由文件，把 URL 模式和 handler 连成边；以及 跨语言桥接：Swift↔ObjC 自动桥接、React Native legacy bridge / TurboModules / Fabric、Expo Modules，JS 调原生方法的调用链能跨语言边界追到底。tree-sitter 静态提取在语言边界会断，CodeGraph 用约定规则把它们接上。

上手：三行命令，不需要 Node

# 1. 装 CLI（自带 Node 运行时，机器上没 Node 也行）
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh
# 或：npm i -g @colbymchenry/codegraph

# 2. 接线：自动检测并配置 Claude Code / Cursor / Codex / Hermes Agent 等
codegraph install

# 3. 每个项目初始化一次（建图 + 开启自动同步）
cd your-project && codegraph init

装完重启 Agent 就能用。日常维护基本为零——自动同步默认开着，唯一要记得的是 codegraph upgrade 保持版本。

命令行同样完整，不给 Agent 用也能自己查：

codegraph explore "auth middleware"    # 一次拿源码 + 调用路径 + 爆炸半径
codegraph callers login_handler        # 谁调用了它
codegraph impact logout_handler        # 改它会波及谁
codegraph affected src/auth.ts         # 哪些测试文件会受影响

# CI 里找受影响的测试：
git diff --name-only HEAD | codegraph affected --stdin --quiet

codegraph affected 这个命令值得单独说：它沿着 import 依赖传递地找出"改了这个源文件，哪些测试文件被影响"，可以直接接进 CI 跑最小测试集——这是把图谱从"帮 Agent 理解"变成"帮团队省 CI 时间"的用法。

和同类项目比，差异在哪

代码智能这赛道我们写过好几篇了，放一起看才清楚 CodeGraph 的位置：

最大差异就两条：自动同步（别人要手动重跑索引，它是文件一改图就更新）和单工具哲学（别人堆工具数，它砍到一个）。64K Star 说明市场对这两个反主流选择是买账的。

实际体验的几个坑

• WSL2 是重灾区——项目放在 /mnt/c 或 /mnt/d 上，MCP 调用会报 Transport closed（本地 socket 在 Windows 盘上不可靠）。README 说现在会回退到进程内模式，但还不行就设 CODEGRAPH_NO_DAEMON=1 跳过共享 server；根治办法是把项目挪到 Linux 原生文件系统（~/ 下）。
• 网络盘 / WSL2 /mnt 上 WAL 起不来——codegraph status 看 Journal: 不是 wal 的话，读会阻塞写，可能出现 database is locked。老版本（0.9 之前）没有自带运行时也容易锁库，先升级。
• 不要共享同一个 .codegraph/ 跨 Windows/WSL——锁和 SQLite 索引跟写它的 OS 绑定。两边各建各的：Windows 侧设 CODEGRAPH_DIR=.codegraph-win。
• stale 窗口真实存在——debounce 默认 2 秒，这 2 秒内 Agent 可能拿到旧图。它用 ⚠️ banner 提示 Agent 直接 Read 文件来兜底，但你要知道这个窗口存在。想调小可以设 CODEGRAPH_WATCH_DEBOUNCE_MS=100（下限 100ms）。
• gitignore 即排除规则——node_modules、dist、build、target、.venv 等默认跳过，哪怕没有 .gitignore。想排除更多就加 .gitignore；已提交进仓库的目录（比如 vendor 主题）要用 codegraph.json 的 exclude 字段，gitignore 管不到已提交的文件。
• 非标准扩展名默认不索引——比如 .tpl 的 PHP、.dota_lua 的 Lua，得在 codegraph.json 里 extensions 映射，改完要重跑 codegraph index。
• 小项目收益有限——100 个文件以内的仓库，省 token 的效果（18-33%）远不如大仓库（90%）。它的价值随代码库规模和缠绕度增长，玩具项目装上属于杀鸡用牛刀。
• 遥测默认开——收集匿名使用统计（哪些工具被用、哪些语言被索引），说是不含代码/路径/查询，介意就 codegraph telemetry off。

适合谁用

• 大型代码库上天天用 Claude Code / Codex / Cursor 的人——这是省 token 最直接的工具，VS Code 仓库那一档（11k 文件）收益最大
• 被 Agent"grep 半天读一堆无关文件"搞烦的人——一次调用拿回精确上下文的体验差异是颠覆性的
• React Native / iOS / Expo 开发者——跨语言调用链是独一份的能力，别的静态分析在语言边界就断了
• 在意数据不出机器的人——无 API key、无云、SQLite 本地文件，删了 .codegraph/ 就什么都没了
• 用 Hermes Agent 的——官方支持列表里就有它，装机器的可以直接 codegraph install 试试

总结

CodeGraph 做的事情一句话：把"Agent 现场 grep 重建代码结构"变成"查一张预先建好、自动保鲜的图谱"。技术选型上它不新——tree-sitter + SQLite + FTS5 都是老东西——但它把三件事做到了位：Rust 内核的性能、自动同步的零维护体验、单工具的设计纪律。

7 个月 64K Star 不是营销堆出来的。在 Agent 工具链普遍还停留在"给 Agent 更多 grep 的变体"时，它给了 Agent 一条真正的捷径。代码库越大、越缠绕，这个捷径越值钱。

项目地址：github.com/colbymchenry/codegraph · 文档：colbymchenry.github.io/codegraph