CodeGraph：给 AI 编程 Agent 装上一张代码知识图谱

一个本地优先的开源项目（MIT），通过 MCP 给 Claude Code、Cursor、Codex、opencode 等编程 Agent 提供语义级代码智能。我读了源码和设计文档，整理成这篇使用说明，方便自己参考，也分享给同样在用 AI 编程工具的人。

它解决什么问题

你写代码时问 Agent「这个函数被谁调用了」「改这个常量会影响什么」「请求怎么走到数据库的」，Agent 默认做法是用 grep 搜符号名，然后一个一个打开文件读，自己脑内拼接调用链。一个流程问题可能要十几次 Read 和 Grep，慢，费 token，还容易漏。

CodeGraph 的做法是把整个代码库解析成符号加调用关系图，存在本地 SQLite 里。Agent 通过 MCP 一次调用，就能拿到相关符号的完整源码、调用路径、影响面。

官方在 7 个仓库的实测，平均省 35% 成本、57% token、46% 时间、71% 工具调用次数。我自己还没跑过 A/B，但代码逻辑看下来是靠谱的。

为什么不需要配置模型就能用

这可能是大家最关心的点。装完直接能用，不配 API Key，不选模型，不需要装 skill。原因就一条：CodeGraph 不调用任何 LLM，它是一个纯确定性的代码解析工具。

整个流程是这样的：用 tree-sitter 把源码解析成 AST（抽象语法树），从 AST 里提取符号（函数、类、路由、变量）和它们之间的静态关系（调用、导入、继承），再做跨文件引用解析和框架识别（Express、Django、Rails、Spring、Gin 等，每种框架一个 resolver），最后全部存进本地 SQLite。整条链路里没有任何一个环节需要 LLM 参与。

提取结果来自语法结构，是确定性的。同一份代码跑十次，结果完全一样。所以它不需要模型，不需要 API Key，不花一分钱 token 费用。

那 Agent 怎么用上它的？通过 MCP。codegraph install 做了两件事：把 MCP server 注入 Agent 配置，同时在 MCP 握手时把使用说明发给 Agent。之后 Agent 在会话里自己判断要不要调 codegraph_explore，你不需要做任何额外操作。

一句话总结：CodeGraph 负责建图和查图，Agent 负责读图和决策。建图不靠模型，靠的是确定的语法解析。

怎么装

三步，每台机器做一次就行。

# 1. 安装 CLI（curl 脚本自带 Node 运行时，不依赖你机器的 Node 版本）
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh

# 2. 接进 Agent（自动检测 Claude Code / Cursor / Codex / opencode…）
codegraph install

# 3. 对每个要建图的项目
cd 你的项目 && codegraph init

如果你机器上已经有 Node，也可以用 npm i -g @colbymchenry/codegraph。

日常使用，完全自动

codegraph init 之后自动同步默认开启。它用系统原生文件监听（macOS FSEvents / Linux inotify）盯着项目目录，你或者 Agent 改代码、增删文件都会增量更新图谱。索引永远新鲜，不需要手动维护。

唯一需要重跑 codegraph init 的场景是项目结构大改或者换了语言配置，一年碰不到一次。

你正常写代码，Agent 在会话里自己决定要不要调 codegraph_explore。完全无感，就跟你在对话里看到 AI 背后自动查资料一样。装好之后新会话自动生效，没 init 的项目 Agent 会提示没有索引，跑一下 codegraph init 就行。

几个手动命令，平时基本用不上，但知道在哪：

命令	用途
codegraph status	看索引状态，装完先跑一次确认正常
codegraph query <符号名>	手动查符号，偶尔用来快速定位
codegraph impact <符号名>	改代码前看影响面
codegraph affected	找受改动源文件影响的测试文件
codegraph sync	手动增量同步，理论上用不上
codegraph uninstall	卸载，加 --keep-cli 只卸 Agent 配置保留 CLI

准确性和资源开销

可解析的流程给确定性答案，解析不了的分派诚实标注边界，绝不瞎连。重名或 overload 有消歧逻辑，比如同名符号返回所有重载的源码让你自己判断。

但要说明一个边界：调不调、调得好不好，最终取决于 Agent 自己的判断。项目文档里记录过，不同模型对工具的采纳率不一样，有些会退回 Read 和 Grep 的老路。对主流 Agent 加 Sonnet 级别以上的模型，日常流程性问题准确度是可靠的。

资源开销方面，文件监听常驻加每次改动增量解析，普通项目几乎无感。超大仓库首次索引时 CPU 会高一阵，建完就正常了。