CLI CodeGraph 为AI编程助手构建本地代码知识图谱

用 Claude Code、Cursor、Codex 这类 AI 编程助手时，最烧钱也最慢的一步往往不是模型推理，而是助手反复调用 Grep、Read、Explore 去“认识”你的代码库。一个中等规模的项目，光是让 agent 搞清楚“这个函数被谁调用、改动会影响哪些测试”，就要消耗大量上下文和工具轮次，任务还没开始，预算已经蒸发一半。
更糟的是，这种上下文每次会话都要重新构建——你昨天让助手理解过的调用关系，今天打开新会话又得再来一遍。CodeGraph 的想法是把“代码长什么样、谁调用谁”预先建成一个一直存在于本地的知识图谱，助手需要时直接查图，而不是每次都重新探索。

项目基本信息

一、项目介绍

colbymchenry/codegraph 是一个面向 AI 编程助手（Claude Code、Codex、Gemini、Cursor、OpenCode、Copilot 等）的本地代码知识图谱工具。它用 Rust 写内核，在你的代码变更时自动同步索引，把符号、调用边、文件、全文检索统一存进本地 SQLite。助手可以通过 MCP 工具一步拿到“相关源码 + 调用流 + 影响半径”，而不是每次都启动 Explore 子代理慢吞吞地扫描。官方强调三件事：最快的完整代码图、手术级上下文、100% 本地运行——数据不出机器。

二、核心优势

1. 完全本地：图谱与索引都落在你的机器上，代码与查询不上传任何云端，对隐私和合规友好。
2. 自动同步：监听文件变更（延迟 <100ms），按默认 2 秒去抖后增量更新，新写的文件下一个查询就能看见。
3. MCP 原生：内置 codegraph serve --mcp，Claude Code 等客户端一行配置即可把图谱当工具调用。
4. 省 token 省轮次：把“探索代码”从多次文件读取收敛成一次图谱查询，显著降低上下文消耗与工具调用次数。
5. 多客户端覆盖：一份索引可同时服务 Claude Code、Cursor、Codex、Copilot、Kiro、Gemini 等。

三、适用场景

• 大型代码库里让 AI 助手快速定位符号、调用方与被影响测试，避免逐文件扫描。
• CI 或 pre-commit 阶段用 codegraph affected 只跑被改动波及的测试，加速反馈。
• 多客户端团队统一一份代码索引，新人助手也能立刻“认识”项目。
• 离线/内网环境里给编程助手提供稳定的代码语义检索。

四、安装教程

macOS / Linux 用官方安装脚本（一行）：

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

Windows（PowerShell）：

irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex

也可以直接用 npm 全局安装：

npm i -g @colbymchenry/codegraph

常见报错：Windows 上若 irm 被执行策略拦截，先执行 Set-ExecutionPolicy -Scope Process RemoteSigned；npm 全局安装后 command not found，通常是 npm 全局 bin 目录不在 PATH，把对应目录加入 PATH 后重载终端即可。

五、使用示例

在项目里初始化并构建索引：

cd your-project
codegraph init

在 Claude Code 等客户端里接入 MCP（配置示例）：

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

查询与影响分析的真实输出示意：

codegraph explore "how does a request reach the database?"
-> 返回相关符号源码 + 调用路径 + 影响半径（一次调用完成）
codegraph affected src/auth.ts --filter "e2e/*"
-> 列出仅 e2e/ 目录下受 auth.ts 改动影响的测试文件

六、常见问题

Q：CodeGraph 会上传我的代码吗？
A：不会。图谱与索引 100% 在本地 SQLite，MCP 服务也只在本地进程跑，不联网上传源码。
Q：支持哪些 AI 客户端？
A：官方列出 Claude Code、Codex、Gemini、Cursor、OpenCode、Copilot、Kiro、Hermes Agent 等，只要能接 MCP 即可。
Q：索引会很占空间吗？
A：索引主要是符号与边关系，体积通常远小于源码本身；可用 codegraph index --force 重建或 unlock 解除卡死的锁文件。

七、总结

CodeGraph 把“让 AI 认识代码库”这件最费 token 的事，从每次会话的重复探索变成一次本地构建、长期复用。对动辄几十万行、又重度使用编程助手团队来说，它是能直接省下 API 成本的基础设施。项目以 MIT 协议开源，内核用 Rust，值得在 CI 与日常开发流里接入。