CodeGraph：AI编程助手的代码知识图谱工具

已安装？运行 codegraph upgrade

关注 X 上的 @getcodegraph 获取更新。

用语义代码智能为 Claude Code、Cursor、Codex、OpenCode、Hermes Agent、GitHub Copilot 以及 Gemini、Antigravity、Kiro 等工具提速

最快的完整代码图谱 · 精准上下文 · 为智能体实际工作方式而生 · 100% 本地运行

文档与官网 →

CodeGraph 平台即将发布——针对每个 PR，准确知道要测试什么、什么可能出问题、受影响的流程有哪些、业务逻辑是否被破坏。

获取托管产品早期测试资格 → getcodegraph.com

框架感知路由

混合 iOS / React Native / Expo 桥接

跨文件覆盖率量化

无需 Node.js——一条命令获取适合你系统的构建：

# 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 i -g @colbymchenry/codegraph

CodeGraph 自带运行时——无需编译，无需原生构建，各平台表现一致。安装程序会将 codegraph 加入 PATH，但不会改变当前 shell——在进行下一步之前打开新的终端，以便命令能够被正确解析。

随时运行 codegraph upgrade 升级——它会检测你的安装方式（bundle、npm 或 npx）并原地更新。添加 --check 查看是否有可用更新，或使用 codegraph upgrade <version> 锁定特定版本。

2. 连接你的智能体

在新终端中运行安装程序，将 CodeGraph 连接到你使用的智能体：

codegraph install

检测并自动配置 Claude Code、Cursor、Codex CLI、opencode、Hermes Agent、GitHub Copilot（VS Code、Copilot CLI、JetBrains IDE）以及 Gemini CLI、Antigravity IDE、Kiro——将 CodeGraph MCP 服务器接入各自环境。这一步是将 CodeGraph 连接到你的智能体；步骤 1 中安装 CLI 本身并不会自动完成这件事。它只负责连接智能体——不会索引任何代码；构建每个项目的图谱是步骤 3 中独立的 codegraph init 。（快捷方式：npx @colbymchenry/codegraph 一键下载并运行此步骤。）

3. 初始化每个项目

cd your-project
codegraph init

codegraph init 在同一步骤中创建本地 .codegraph/ 目录并构建完整图谱——一条命令，搞定。

自动同步默认开启。CodeGraph 会监视项目并在每次文件变更时更新图谱——无论是你在编辑代码，还是添加、修改、删除文件。索引永不过期，无需重新运行。

改变主意了？一条命令从所有已配置的智能体中移除 CodeGraph，同时移除 CLI 本身——它会找到的每一种安装（独立 bundle、npm 全局包、启动器链接），在删除前向你展示：

codegraph uninstall

传入 --keep-cli 可仅移除智能体配置而保留 CLI。

此操作反转安装程序的行为——从每个已配置的智能体中剥离 CodeGraph 的 MCP 服务器配置、指令和权限。你的项目索引（.codegraph/）会保留；用 codegraph uninit 按项目移除。使用 --target 可指定移除特定智能体，或使用 --yes 以非交互模式运行。

以下每种语言都采用相同处理方式——完整的结构化提取和跨文件解析为统一图谱，无需针对每种语言单独配置：

各语言详情——扩展名、框架以及具体提取内容——请参阅支持的语言。

当 AI 智能体需要理解代码时——无论是回答问题还是做出修改——它只能缓慢地发现结构：逐个文件地 grep、glob 和 Read，手动重建调用路径和依赖关系。这在一开始就堆砌了大量工具调用和往返通信，远未开始真正的工作。

CodeGraph 在一次调用中就把智能体需要的精确代码交给它。它是一个预构建的知识图谱，涵盖代码库中每个符号、调用边和依赖关系——因此智能体不再需要逐文件爬取，而是问一个问题就能得到相关源码、符号间的调用路径（包括 grep 无法跟随的动态分派跳转），以及变更的影响范围。精准的上下文，而非逐文件搜索——这意味着在每个代码库上（无论大小）都能减少工具调用次数并获得更快的答案。

关于成本：CodeGraph 在每个代码库上的优势都源于精确性——智能体不再爬取文件，而是从图谱中获取答案。在当前模型上，这种精确性也带来了显著直接节省：2026-08 的重新测量（在两个分支都阻止 CLI 运行的测试框架上）显示，跨七个基准代码库平均成本降低了 44%，令牌消耗减少了 62%，因为没有图谱的强大模型会在重新推导结构时耗尽预算。成本更多取决于问题所需的发现程度，而非代码库的原始规模：需要 28–43 次工具调用才能回答的问题上，成本下降了 57–78%；而只需 7 次就能回答的问题上，成本几乎持平。

关于上下文：上述数字衡量的是吞吐量——处理的令牌数、调用的工具数、得到一个答案所花费的美元数。它们没有衡量的是你的上下文窗口里还残留着什么，而在这个维度上 CodeGraph 反而成本更高，而非更低。在同一七个代码库的多轮会话中，CodeGraph 的响应在会话结束时残留的检索上下文比文件读取智能体多约 80%——在 VS Code 上，是 67k 令牌对比 18k。机制与它快速的原因相同：CodeGraph 返回一个密集的、逐字的载荷来回答问题，然后留在窗口中，而 grep-and-read 智能体则遍历许多被逐出的小结果。处理的令牌更少与更大的持久占用同时存在，都是真实的。如果你需要在小窗口中运行长会话，要为此做好预算。按代码库衡量的详情见：docs/benchmarks/residual-context-occupancy.md。

在 7 个真实世界的开源代码库（涵盖 7 种语言）中测试，比较一个智能体（Claude Code，无头模式）回答一个架构问题时有 CodeGraph 和没有 CodeGraph 的表现，取每轮 4 次运行的中位数。2026-08-05 使用 Claude Opus 4.8 针对当前构建版本重新测量，测试框架在两个分支都阻止 codegraph CLI——污染行：28 个无图谱运行中有 0 个被污染。

全面获胜——每个代码库、每个规模：工具调用减少 88% · 速度快 53% · 令牌减少 62% · 成本降低 44% · 七个代码库上的文件读取均降至零。

有索引可用时，智能体回答只需一至四次 codegraph_explore 调用即停止。没有它，智能体则在发现上耗尽预算——多达 43 次工具调用和 19 次文件读取，重新推导图谱早已知道的内容。在这次测量中，每个代码库使用 CodeGraph 都更快——最窄问题快 35%，最宽问题快 3.6 倍。

¹ 成本追踪问题所需的发现程度，这就是为什么它比其他列变化大得多：在文件读取分支需要 28–43 次工具调用的代码库上下降 57–78%，但在 Django 和 Gin 上只有 13%，因为那些代码库上它分别只需 14 次和 7 次就得到答案。有图谱的分支仍然只需 3 次和 1 次调用，零文件读取。文件读取 = 打开的文件中位数——手术刀般精准的上下文优势集中在一列中：当 CodeGraph 存在时，智能体在七个代码库上从不读取文件。

方法论。每轮都是 claude -p（Claude Opus 4.8, claude-opus-4-8）无头运行针对代码库，--strict-mcp-config：WITH = CodeGraph 的 MCP 服务器启用，WITHOUT = 空 MCP 配置。内置的 Read/Grep/Bash 两个分支均可使用。每个代码库相同问题，每轮 4 次运行，报告中位数。成本 = 运行的 total_cost_usd；令牌 = 处理的令牌总数，按每个助手轮次求和（输入含缓存读取 + 缓存创建 + 输出）；时间 = 墙上时钟；工具调用 = 每次工具调用，包括模型生成的任何子智能体内部的调用。代码库以 --depth 1 克隆，由同一 CodeGraph 构建版本为其建立索引并提供服务。2026-08-05 针对当前构建版本重新测量。

codegraph CLI 在两个分支都被阻止。清理过的 PATH 加上 PreToolUse 钩子拒绝任何 Bash 调用 CLI，WITHOUT 分支和 WITH 分支都是如此。这很关键：没有这个阻止，对照分支就不是对照分支了。在未阻止的测试框架上，我们测量到 WITHOUT 智能体在 28 次运行中有 26 次在 PATH 上找到了 CLI 并通过 Bash 调用 CodeGraph——这在两个方向上都扭曲了比较，因为 CLI 调用不算作工具调用且其输出仍然进入窗口。早期发布的数字是在没有这个阻止的情况下产生的。在上述报告中，所有 28 次 WITHOUT 运行都尝试调用 CLI 且全部被阻止——0 次污染。

CodeGraph 获胜的原因：有索引可用时，智能体直接回答——通常一次 codegraph_explore 返回相关源码——然后停止，在所有基准代码库上零文件读取。没有它，智能体在读取正确代码之前将大部分预算花在发现上（find/ls/grep）。CodeGraph 只有被直接查询才有用，所以它的指令引导智能体直接回答，而不是将探索委托给文件读取子智能体——否则子智能体会读取文件，CodeGraph 就成了开销。

为速度而生——Rust 内核

CodeGraph 的解析引擎是一个原生 Rust 内核：20 种语言——TypeScript、JavaScript、Java、Python、Go、C、C++、Rust、C#、Ruby、PHP、Swift、Kotlin、Scala、Dart、R、Lua、Luau（Metal 和 CUDA 走 C++ 路径）——在编译代码中解析，每个文件一次边界跨越。每种语言只有在它的图谱在真实代码库上（从小库到 Linux 内核）逐字节与参考引擎相同后才发布；没有预构建二进制文件的平台和有语法错误的文件自动逐文件回退，图谱结果相同。

而且它能自适应运行它的机器。 worker 池、并行解析和分析缓存的大小根据系统实际配置来确定——真实核心数（感知容器/cgroup，所以授予 2 核的 VPS 按 2 核配置，而非主机的 64 核）、macOS 和 Linux 上如实测量的可用 RAM，以及项目解析工作的实测成本：

在工作站上：完整并行管道——原生解析 worker、时刻准备在值得时启动的多 worker 解析器池、内存门控的分析缓存。Swift 编译器仓库（27k 个 Swift 和 C++ 文件）全新索引约需 100 秒；单文件编辑重新同步约需 4 秒。

在 2 核 / 6GB VPS 上：同样的图谱，来自调优为必完成的管道——Linux 内核（70k 文件、2M 符号、6.4M 关系）在不到 12 分钟内索引完成，而内存优先的设计在达到 1% 之前就耗尽内存了。

从第一天开始每天：保存文件在不到一秒内更新图谱——监视器在单独保存后 300ms 触发并同步确切变化的内容（4,400 文件项目约 0.3s，27,000 文件的 Swift 编译器仓库约 0.4s），从不重新扫描树。与最快的竞争索引器的变更时重新索引对比：在 31 个代码库、30 种语言的基准测试中，大型和更大规模代码库上快 2–7 倍——差距随代码库规模增大而扩大，因为它们的成本随仓库增长而增长，而我们的成本随变更增长。

当你的智能体（Claude Code、Cursor、Codex、opencode）启动 codegraph serve --mcp 时，三层机制保持索引与代码同步——并确保智能体在编辑和下次同步之间的短暂窗口内永远不会得到静默的错误答案：

带防抖自动同步的文件监视器。原生 FSEvents / inotify / ReadDirectoryChangesW 监视器捕获每个源文件的创建/修改/删除，并在防抖窗口后触发重新索引（默认 2000ms，可通过 CODEGRAPH_WATCH_DEBOUNCE_MS 调优，夹紧至 [100ms, 60s]）。突发编辑合并为一次同步。

带防抖自动同步的文件监视器。原生 FSEvents / inotify / ReadDirectoryChangesW 监视器捕获每个源文件的创建/修改/删除，并在防抖窗口后触发重新索引（默认 2000ms，可通过 CODEGRAPH_WATCH_DEBOUNCE_MS 调优，夹紧至 [100ms, 60s]）。突发编辑合并为一次同步。

每个文件的过期提示。在短暂的防抖窗口期间，如果 MCP 工具响应会引用仍待处理的文件，则在前面加上 ⚠️ 横幅命名该文件并告知智能体直接 Read 它。未被响应引用的待处理文件则作为小页脚显示。无论哪种方式，智能体都得到明确的信号——已通过 Claude Code 验证，智能体在打开文件之前会说"直接读取文件以获取最新内容"。

Per-file staleness banner。在短暂的防抖窗口期间，MCP 工具响应中涉及仍在待处理状态文件的，会在前面加上 ⚠️ 横幅，标出文件名并告知 Agent 直接读取该文件。响应中未涉及的待处理文件则显示在底部小字中。无论哪种方式，Agent 都会收到明确的信号——这已在 Claude Code 中得到验证，Agent 会在打开文件前直接说"正在读取文件的实时内容"。

Connect-time catch-up。当 MCP 服务器（重新）连接时，codegraph 会在回答第一个查询前，对工作树运行快速的（文件大小、修改时间）+ 内容哈希对账——因此，在没有 MCP 服务器运行期间所做的编辑（终端中的 git pull、其他编辑器的编辑、之前已退出的 Agent 会话）会在下一个会话的第一次工具调用时被吸收。

agent writes src/Widget.ts
  → watcher fires (<100ms)
  → debounce (default 2s)
  → sync; Widget.ts is in the index
  → next agent query sees it

随时用 codegraph status（CLI 命令）验证。如果有任何待处理内容，你会看到 ### Pending sync: 部分，列出文件名及其编辑时间。

少数需要手动执行 codegraph sync 的场景：watcher 被禁用时（沙盒环境，或 CODEGRAPH_NO_DAEMON=1），或者在 Agent 会话外编写脚本访问索引，并希望在脚本开始时进行预检同步。

→ 完整深入讲解见 Guides → Indexing a Project。

Framework-aware Routes

CodeGraph 检测 Web 框架的路由文件，并发出路由节点，通过引用边连接到对应的处理器类或函数。现在查询视图/控制器的调用方时，可以看到绑定它的 URL 模式。

Routers — routes and the navigation between them

这些框架还会额外发出 navigates 边：将用户导航到某处的函数与它所命名的屏幕链接起来，这样"点击这里会跳转到哪里"在图中只是一跳，而不是一次搜索。每个都读取字面目标——计算出的目标，或没有路由服务的路径，保持未解析状态而非猜测——以 markup 形式编写的链接会被标记为推断。

在包含多个 app 的仓库中，每个 app 的路由只与该 app 内部编写的导航进行匹配。

Mixed iOS / React Native / Expo bridging

真实的 iOS 和 React Native 代码库横跨多种语言——Swift 调用方通过自动桥接调用 Objective-C 选择器，JS 文件通过 React Native 桥接调用原生模块，JSX 组件委托给原生视图管理器。静态 tree-sitter 提取在每种语言边界处停止。CodeGraph 桥接这些边界，使 codegraph_explore 能够端到端地连接跨语言的流程——调用路径和影响范围穿过边界继续延伸，而不是在边界处停止。

已在真实代码库（小、中、大型）上验证了每种桥接：

每个桥接跳跃都标注了它是如何进入图的。由桥接解析器匹配的跳跃携带 metadata.resolvedBy: 'framework' 和 metadata.framework 来命名解析器（swift-objc-bridge、react-native-bridge、expo-modules-js、fabric-view）。合成的通道被标记为 provenance:'heuristic'，并带有 metadata.synthesizedBy（rn-event-channel、fabric-native-impl）。

npx @colbymchenry/codegraph

询问要配置哪个 Agent——自动检测已安装的：Claude Code、Cursor、Codex CLI、opencode、Hermes Agent、 Gemini CLI、Antigravity IDE、Kiro、GitHub Copilot（VS Code、Copilot CLI、JetBrains IDE）

提示将 codegraph 安装到 PATH（以便 Agent 启动 MCP 服务器）

询问配置是适用于所有项目还是仅当前项目

为每个选定的 Agent 写入 MCP 服务器配置，并在 Agent 的指令文件（CLAUDE.md / AGENTS.md / GEMINI.md）中添加一个带标记围栏的小 CodeGraph 部分——这是子 Agent 和非 MCP Agent 学习 codegraph explore 命令的方式，因为 MCP 服务器自身的指引只到达主 Agent。通过 codegraph uninstall 可清除。

当 Claude Code 是目标之一时，设置 auto-allow 权限

安装程序只负责将 Agent 接入——它不会索引代码。完成后，需要对每个项目运行 codegraph init 构建图（步骤 3）。一个全局 codegraph 安装可以覆盖所有项目；每个项目只需运行一次 codegraph init。

非交互式（脚本 / CI）：

codegraph install --yes                              # 自动检测 Agent，全局安装
codegraph install --yes --init                       # 同上，然后构建当前项目的索引（一次性引导）
codegraph install --target=cursor,claude --yes       # 显式指定目标列表
codegraph install --target=auto --location=local     # 检测到的 Agent，项目本地
codegraph install --target=copilot-vscode,copilot-cli,copilot-jetbrains --yes  # GitHub Copilot 全面配置
codegraph install --print-config codex               # 仅打印代码片段，不写入文件
codegraph install --print-config copilot-vscode      # 同上，面向 VS Code 中的 Copilot

2. 重启你的 Agent

重启你的 Agent（Claude Code / Cursor / Codex CLI / opencode / Hermes Agent / Gemini CLI / Antigravity IDE / Kiro / VS Code、Copilot CLI 或 JetBrains IDE），以加载 MCP 服务器。

3. 初始化项目

cd your-project
codegraph init

构建每个项目的知识图谱索引，之后在每次文件更改时自动同步。一个全局 codegraph 安装可以在你打开的每个项目中工作——无需每个项目都重新运行安装程序。添加 --yes 跳过所有提示（脚本 / CI / 容器引导）。

就这样——当 .codegraph/ 目录存在时，你的 Agent 会自动使用 CodeGraph 工具。

npm install -g @colbymchenry/codegraph

添加到 ~/.claude.json：

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

alwaysLoad 使 codegraph_explore 从第一个 prompt 就加载。否则 Claude Code 会将每个 MCP 工具延迟到工具搜索步骤之后，因此新的会话只能看到工具名称，直到模型搜索到它为止。

添加到 ~/.claude/settings.json（可选，用于 auto-allow）：

{
  "permissions": {
    "allow": [
      "mcp__codegraph__*"
    ]
  }
}

一个通配符即可自动批准所有 codegraph 相关的工具调用。