AI 代理的导航地图

用过 AI 编程工具的人都知道一个怪现象：每次你跟 Claude Code 说「帮我看下这个函数在哪里定义的」，它就开始 grep→glob→Read，翻遍整个项目文件。翻就翻了，下次新会话又要重来一遍。

CodeGraph 解决的就是这个浪费。它给 AI 代理建了一个预编译的代码知识图谱——所有符号定义、函数调用关系、类和接口的继承链、导入路径……全部提前解析好存在 SQLite 里。AI 不用再「探索」代码库，直接查图就行。

根据作者的基准测试（在 7 个真实仓库上跑），CodeGraph 平均能：减少 47% token、降低 58% 工具调用、提速 22%。个别项目甚至省了 40% 的成本。

先看效果

CodeGraph 演示

同样是问「Django 的 ORM 怎么做查询的」，没有 CodeGraph 要 13 次工具调用、9 次文件读取、1.4M token；有了它只要 3 次工具调用、0 次文件读取、559k token。省了一半不止。

安装（三种方式）

方式一：独立安装（无需 Node.js，推荐）

curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh

安装器会下载对应平台的可执行文件（已捆绑 Node 运行时）。安装后必须打开新终端才能生效。

方式二：npm 安装

npm i -g @colbymchenry/codegraph

方式三：临时使用

npx @colbymchenry/codegraph

Windows 也有 PowerShell 安装脚本，Linux/macOS/Windows 都支持 x64 和 arm64。

完整使用流程（重点）

第 1 步：安装并连接代理

装完 CLI 后，运行这个命令把 CodeGraph 接入你的 AI 代理：

codegraph install

它会自动检测你电脑上装了哪些 AI 编程工具（Claude Code、Cursor、Codex CLI、Gemini CLI、Kiro、opencode、Hermes Agent、Antigravity IDE），然后交互式地问你：

  • 要接入哪些代理？（自动检测已安装的）
  • 配置应用范围：全局还是当前项目？
  • 是否设置 Claude Code 的自动允许权限？

你不需要手动写任何 MCP 配置文件。这一步不能跳过——只装 CLI 不接代理是没用的。

不想交互可以加 --yes：

codegraph install --yes                              # 全部自动
codegraph install --target=cursor,claude --yes       # 只连 Cursor 和 Claude Code

第 2 步：重启你的 AI 代理

让代理重新加载 MCP 服务器配置。对于 Claude Code，退出重进即可。

第 3 步：初始化项目并建索引

cd your-project
codegraph init -i

这一步干了三件事：

  1. codegraph init —— 在项目根目录创建 .codegraph/ 目录
  2. -i（即 --index） —— 立即开始解析代码、建知识图谱
  3. 生成 SQLite 数据库 .codegraph/codegraph.db，包含所有符号、边、FTS5 全文索引

建索引的时间取决于项目大小——中小型项目几秒到几十秒。这是一个一次性成本，之后所有 AI 代理的每个会话都受益。

如果后续项目代码有大量变更，可以手动触发重新索引：

codegraph index

第 4 步：正常使用 AI 代理

现在你正常跟 AI 对话就行。当问到跟代码结构相关的问题时，代理会自动调用 CodeGraph 的 MCP 工具查图，而不是自己去翻文件。

比如你问：「帮我看下这个请求从入口到数据库的完整流程」，代理会调用 codegraph_explore，一步返回所有相关符号、文件分组、调用关系图。

CodeGraph 给代理提供了哪些工具？

接入后，AI 代理多了以下能力：

工具 作用
codegraph_explore 最常用。一次调用回答「某个模块怎么工作的」——返回符号源码、关系图、影响范围。还能发现回调、React 重渲染、接口实现等动态跳转。
codegraph_search 按名称搜索符号，全代码库 FTS5 全文搜索
codegraph_callers 查找谁调用了某个函数/方法
codegraph_callees 查找某个函数调用了什么
codegraph_impact 分析修改某个符号的影响范围
codegraph_node 查看某个符号的详细信息+完整源码
codegraph_files 浏览已索引的文件结构（比文件系统扫描快）
codegraph_status 检查索引健康状态和统计信息

索引自动同步：改了代码怎么办？

CodeGraph 有 三层自动同步，基本不需要手动维护：

  1. 文件监听器——用操作系统原生事件（macOS 用 FSEvents、Linux 用 inotify、Windows 用 ReadDirectoryChangesW），文件变更后防抖 2 秒自动增量同步。多次快速保存会合并成一次同步。
  2. 陈旧提示——在防抖窗口期内，如果 AI 查询涉及刚修改的文件，CodeGraph 会返回一个横幅提醒「这个文件有改动正在同步中」，AI 会直接去读文件内容而不是用旧索引。
  3. 重连同步——MCP 服务器每次重连（新会话、新代理）时，会先对比文件大小 + 修改时间 + 内容哈希，把外部改动（如 git pull、编辑器外部修改）同步回来。

如果需要关闭文件监听（比如在 CI 环境）：

export CODEGRAPH_NO_DAEMON=1

更高级的用法

CI 中找出受影响的测试

git diff --name-only HEAD | codegraph affected --stdin --quiet

这个命令会遍历文件依赖关系，找出当前改动影响了哪些测试文件。配合 CI 用：

git diff --name-only HEAD | codegraph affected --stdin --quiet | xargs npx vitest run

多个项目

codegraph install 只需要做一次（全局配置），之后每个新项目只需跑 codegraph init -i 建索引就行。

手动 MCP 配置

如果你不想用安装器，可以在 ~/.claude.json 手动添加：

{
  "mcpServers": {
    "codegraph": {
      "type": "stdio",
      "command": "codegraph",
      "args": ["serve", "--mcp"]
    }
  }
}

程序化使用

也可以作为库嵌入到自己的工具里：

npm i @colbymchenry/codegraph

然后导入 CodeGraph 类，调用 .searchNodes()、.getCallers()、.buildContext() 等 API。

支持的语言和框架

CodeGraph 使用 tree-sitter 解析代码，支持 20+ 种语言：TypeScript、JavaScript、Python、Go、Rust、Java、C#、PHP、Ruby、C、C++、Objective-C、Swift、Kotlin、Scala、Dart、Svelte、Vue、Lua、Luau、Pascal、Liquid。

还识别 14 种 Web 框架的路由模式：Django、Flask、FastAPI、Express、NestJS、Laravel、Rails、Spring、Gin、Axum、ASP.NET、Vapor 等——路由文件会被解析，URL 模式和处理器函数自动关联。

对于跨语言项目（比如 React Native），还做了 Swift↔ObjC 桥接、RN 原生模块 ↔ JS 的关联。

卸载

codegraph uninstall     # 从所有 AI 代理中移除 CodeGraph 配置
codegraph uninit        # 从项目中移除 .codegraph/ 数据

我的看法

CodeGraph 是我最近看到的「性价比最高」的 AI 开发工具。它不是另一个花哨的 AI 功能，而是解决了实际的不效率——AI 代理每次都在重新「发现」你的代码，这本身就是浪费。

尤其是对大型项目、多人协作的项目，收益非常明显。37.9k Star 说明市场也认可这个方向。

几个亮点特别值得提：

  • 零配置——没有配置文件，排除规则直接用 .gitignore，大大降低了上手门槛
  • 100% 本地——所有数据在 SQLite 里，不离机，不需要 API key
  • 自动同步——三层机制保证了索引不会变脏
  • 跨平台——不仅是跨 OS，还跨 AI 代理（14 种编程工具都能接）

硬要说缺点的话：首次建索引对超大型项目可能比较慢，以及如果你只用 AI 做简单的代码生成、不涉及代码理解，那 CodeGraph 帮助有限。但对重度用户来说，这几乎是个必装工具。

项目地址：colbymchenry/codegraph · 许可：MIT · 🌟 37.9k Stars（截至 2026-06-02）