开始使用

1. 安装 CLI

无需 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

2. 连接你的 AI 代理

在一个新终端中，运行安装程序以将 CodeGraph 连接到你所使用的 AI 代理：

codegraph install

_{自动检测并配置 Claude Code, Cursor, Codex CLI, opencode, Hermes Agent, Gemini CLI, Antigravity IDE 和 Kiro — 将 CodeGraph MCP 服务器接入每一个。这一步才是将 CodeGraph 连接到你的 AI 代理的关键步骤； 仅在第 1 步安装 CLI 并不会自动完成。（快捷方式：npx @colbymchenry/codegraph 会一次性下载并运行。）}

3. 初始化每个项目

cd your-project
codegraph init

_{codegraph init 会创建本地的 .codegraph/ 目录，并在同一步中构建完整的图谱 — 一条命令，全部完成。}

4. 无需再同步！

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

卸载

改变主意了？一条命令即可从它所配置的每个 AI 代理中移除 CodeGraph：

codegraph uninstall

_{撤销安装程序 — 从每个已配置的 AI 代理中移除 CodeGraph 的 MCP 服务器配置、指令和权限。你的项目索引（.codegraph/）会被保留；如需逐个项目删除，请使用 codegraph uninit。使用 --target 指定要移除的 AI 代理，或使用 --yes 进行非交互式运行。}

为什么选择 CodeGraph？

当 Claude Code 探索代码库时，它会生成探索代理，使用 grep、glob 和 Read 扫描文件 — 每次工具调用都会消耗 Token。

CodeGraph 为这些 AI 代理提供了一个预索引的知识图谱 — 符号关系、调用图和代码结构。AI 代理可以即时查询图谱，而无需扫描文件。

基准测试结果

在 7 个真实开源代码库（涵盖 7 种语言）上进行测试，对比一个 AI 代理（Claude Code，无头模式）回答一个架构问题时，使用和未使用 CodeGraph 的情况。每个单元格数据来自四轮运行中位数下的节省量。已在 Opus 4.8（2026-06-02）上重新验证，使用的是当前构建版本（以 codegraph_explore 为主要工具）。

平均：便宜16% · Token 减少47% · 快22% · 工具调用减少58%

CodeGraph 在每个仓库中都削减了Token、工具调用和实际耗时 — 覆盖小型、中型和大型代码库 — 并且以近乎零文件读取的方式给出答案，而未使用 CodeGraph 的 AI 代理则将预算花费在 grep/find/Read 探索上。codegraph_explore 会完整展示答案 — 包括机制以及你询问的确切方法，即使它们隐藏在数千行的文件中 — 同时将冗余的可互换实现折叠为签名，因此响应的大小取决于答案本身，而不是文件数量。成本在整个过程中保持持平或更低 — 在小型仓库（Alamofire、OkHttp）上节省最大，在那些响应最密集的仓库（Excalidraw、Tokio）上大致持平，此时 CodeGraph 将无 CodeGraph 的 AI 代理所进行的多次小规模 grep/read 往返，换成了少数几个大型、缓存密集的响应。

关键特性

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（通过 MCP）或 codegraph status（CLI）。如果有任何待处理项，你会看到一个 ### Pending sync: 的部分，其中会列出文件名及其编辑时长。

以下少数情况下手动 codegraph sync 是合理的：文件监控器被禁用（沙盒环境，或 CODEGRAPH_NO_DAEMON=1），或者你在代理会话之外对索引进行脚本操作，并希望在脚本开始时进行一次预同步。

→ 完整深入介绍请参阅 指南 → 索引项目。

框架感知路由

CodeGraph 能够检测 Web 框架的路由文件，并生成通过 references 边连接到其处理类或函数的 route 节点。查询视图/控制器的调用者时，现在会显示绑定的 URL 模式。

混合 iOS / React Native / Expo 桥接

真实 iOS 和 React Native 代码库横跨多种语言——Swift 调用者调用一个已自动桥接的 Objective-C 选择器，JS 文件通过 React Native 桥调用原生模块，JSX 组件委托给原生视图管理器。静态 tree-sitter 提取在每个语言边界处停止。CodeGraph 将它们桥接起来，使得 trace、callers、callees 和 impact 能够在整个跨语言间隙中端到端连接。

在真实代码库上验证过（每种桥接的小型 + 中型 + 大型）：

每个桥接发出的边都带标签 provenance:'heuristic'，且 metadata.synthesizedBy: 设置为一个稳定的通道名称（例如 swift-objc-bridge、rn-event-channel、fabric-native-impl、expo-module-extract），以便代理一眼就能看出该跳转是如何进入图的。

快速开始

1. 运行安装器

npx @colbymchenry/codegraph

安装器会：

• 询问要配置哪些代理——自动检测已安装的代理：Claude Code、Cursor、Codex CLI、opencode、Hermes Agent、Gemini CLI、Antigravity IDE、Kiro
• 提示是否将 codegraph 安装到 PATH 中（以便代理可以启动 MCP 服务器）
• 询问配置是应用于所有项目还是仅当前项目
• 为每个选定的代理写入 MCP 服务器配置，并在代理的指令文件（CLAUDE.md / AGENTS.md / GEMINI.md）中写入一个小的标记围栏代码图部分——这样一来，子代理和非 MCP 代理也能学习 codegraph explore / codegraph node 命令，因为 MCP 服务器自身的指导只到达主代理。通过 codegraph uninstall 可干净移除。
• 当 Claude Code 是目标之一时，设置自动允许权限
• 初始化当前项目（仅限本地安装）

非交互式（脚本 / CI）：

codegraph install --yes                              # auto-detect agents, install global
codegraph install --target=cursor,claude --yes       # explicit target list
codegraph install --target=auto --location=local     # detected agents, project-local
codegraph install --print-config codex               # print snippet, no file writes

2. 重启 Agent

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

3. 初始化项目

cd your-project
codegraph init

构建项目级知识图谱索引，之后在每次文件变更时自动同步。一次全局 codegraph install 在你打开的每个项目中均有效——无需在每个项目中重新运行安装程序。

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

npm install -g @colbymchenry/codegraph

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

{
  "permissions": {
    "allow": [
      "mcp__codegraph__codegraph_search",
      "mcp__codegraph__codegraph_explore",
      "mcp__codegraph__codegraph_callers",
      "mcp__codegraph__codegraph_callees",
      "mcp__codegraph__codegraph_impact",
      "mcp__codegraph__codegraph_node",
      "mcp__codegraph__codegraph_status",
      "mcp__codegraph__codegraph_files"
    ]
  }
}

工作原理

┌───────────────────────────────────────────────────────────────────┐
│                            Claude Code                            │
│                                                                   │
│   "How does a request reach the database?"                        │
│       calls CodeGraph tools directly — no Explore sub-agent       │
│                                 │                                 │
└─────────────────────────────────┬─────────────────────────────────┘
                                  │
                                  ▼
┌───────────────────────────────────────────────────────────────────┐
│                        CodeGraph MCP Server                       │
│                                                                   │
│       explore · search · callers · callees · impact · node        │
│                                 │                                 │
│                                 ▼                                 │
│                       SQLite knowledge graph                      │
│          symbols · edges · files · FTS5 full-text search          │
└───────────────────────────────────────────────────────────────────┘

1. 提取 — tree-sitter 将源码解析为 AST。语言特定的查询提取节点（函数、类、方法）和边（调用、导入、继承、实现）。

2. 存储 — 所有数据存入本地 SQLite 数据库（.codegraph/codegraph.db），并启用 FTS5 全文搜索。

3. 解析 — 提取后，解析引用关系：函数调用 → 定义、导入 → 源文件、类继承以及框架专属模式。

4. 自动同步 — MCP 服务器使用原生 OS 文件事件监视项目。变更以去抖方式（2秒静默窗口）处理，仅过滤源文件并增量同步。你编码时图谱始终保持最新——无需配置。

CLI 参考

codegraph                         # Run interactive installer
codegraph install                 # Run installer (explicit)
codegraph uninstall               # Remove CodeGraph from your agents (inverse of install)
codegraph init [path]             # Initialize in a project (--index to also index)
codegraph uninit [path]           # Remove CodeGraph from a project (--force to skip prompt)
codegraph index [path]            # Full index (--force to re-index, --quiet for less output)
codegraph sync [path]             # Incremental update
codegraph status [path]           # Show statistics
codegraph unlock [path]           # Remove a stale lock file that's blocking indexing
codegraph query <search>          # Search symbols (--kind, --limit, --json)
codegraph explore <query>         # Relevant symbols' source + call paths in one shot (same output as the codegraph_explore MCP tool)
codegraph node <symbol|file>      # One symbol's source + callers, or read a file with line numbers (same output as codegraph_node)
codegraph files [path]            # Show file structure (--format, --filter, --max-depth, --json)
codegraph callers <symbol>        # Find what calls a function/method (--limit, --json)
codegraph callees <symbol>        # Find what a function/method calls (--limit, --json)
codegraph impact <symbol>         # Analyze what code is affected by changing a symbol (--depth, --json)
codegraph affected [files...]     # Find test files affected by changes (see below)
codegraph daemon                  # Manage background daemons — pick one to stop (alias: daemons)
codegraph telemetry [on|off]      # Show or change anonymous usage telemetry
codegraph upgrade [version]       # Update to the latest release (--check, --force)
codegraph version                 # Print the installed version (also -v, --version)
codegraph help [command]          # Show help, optionally for one command

codegraph affected

通过传递性地追踪导入依赖关系，找出受变更源文件影响的测试文件。

codegraph affected src/utils.ts src/api.ts         # 将文件作为参数传入
git diff --name-only | codegraph affected --stdin   # 从 git diff 管道输入
codegraph affected src/auth.ts --filter "e2e/*"     # 自定义测试文件模式

CI/钩子示例：

#!/usr/bin/env bash
AFFECTED=$(git diff --name-only HEAD | codegraph affected --stdin --quiet)
if [ -n "$AFFECTED" ]; then
  npx vitest run $AFFECTED
fi

MCP 工具

当作为 MCP 服务器运行时，CodeGraph 提供一组聚焦的四个工具——实测的智能体行为表明，更精简的列表能引导智能体选择正确的工具，并节省每次会话的上下文：

另外四个工具（codegraph_callees、codegraph_impact、codegraph_files、codegraph_status）保持完全可用但默认不列出——根据评估运行测量，智能体从未或极少选择它们，且它们的信息已内联包含在上述四个工具中（explore 的影响范围部分、node 的依赖项注释、符号体作为其被调用者列表）。可通过 CODEGRAPH_MCP_TOOLS 环境变量重新启用其中任何一个（例如 CODEGRAPH_MCP_TOOLS=explore,node,search,callers,impact），或使用它们的 CLI 等效命令（codegraph callees / impact / files / status）。

在工作区中没有 .codegraph/ 索引时，服务器会声明自身为非活跃状态，并且不列出任何工具——智能体正常使用其内置工具，索引操作由您决定。

库使用

CodeGraph 可以直接嵌入。npm 包重新导出了其编程 API，因此 import 和 require 都能解析到您自己进程中的 CodeGraph 类——方便将其嵌入到应用程序中（例如 Electron 主进程）。

import CodeGraph from '@colbymchenry/codegraph';
// CommonJS 同样有效：
//   const { CodeGraph } = require('@colbymchenry/codegraph');

const cg = await CodeGraph.init('/path/to/project');
// 或者：const cg = await CodeGraph.open('/path/to/project');

await cg.indexAll({
  onProgress: (p) => console.log(`${p.phase}: ${p.current}/${p.total}`)
});

const results = cg.searchNodes('UserService');
const callers = cg.getCallers(results[0].node.id);
const context = await cg.buildContext('fix login bug', { maxNodes: 20, includeCode: true, format: 'markdown' });
const impact = cg.getImpactRadius(results[0].node.id, 2);

cg.watch();   // 文件变更时自动同步
cg.unwatch(); // 停止监听
cg.close();

从同一入口点导出了更底层的构建块，供直接驱动图的调用者使用：DatabaseConnection、QueryBuilder、getDatabasePath、initGrammars / loadGrammarsForLanguages 和 FileLock。

嵌入要求

• 从 npm 安装（npm i @colbymchenry/codegraph），以便匹配的跨平台包（包含编译后的库及其依赖项）与 shim 一起获取。
• API 在您的运行时上运行，因此需要 Node 22.5+ 以使用内置的 node:sqlite（当 Electron 捆绑的 Node 版本为 22.5+ 时也符合条件）。CLI 和 MCP 服务器不受影响——它们运行在自包含的捆绑运行时上。
• TypeScript 类型随包一起提供。与任何面向 Node 的库一样，请确保 @types/node 可用，并设置 skipLibCheck: true（常见默认值）。

配置

没有任何配置——CodeGraph 是零配置的，无需编写或同步任何配置文件。语言支持根据文件扩展名自动完成；无需为每种语言进行额外配置。

默认跳过的内容：

• 依赖、构建和缓存目录——node_modules、vendor、dist、build、target、.venv、Pods、.next 以及所有支持的栈中的类似目录——因此图只包含您的代码，而非第三方噪音。即使没有 .gitignore 也适用。
• .gitignore 中的任何内容——在 git 仓库中通过 git 识别，在非 git 项目中通过直接读取 .gitignore（根目录及嵌套）识别。
• 大于 1 MB 的文件——生成的捆绑包、压缩后的 JS、供应商 blob。

要排除其他内容，请将其添加到 .gitignore。要将默认排除的目录重新包含（例如您确实希望索引某个供应商依赖项），请添加否定规则——!vendor/。默认设置统一应用，因此提交依赖项或构建目录不会强制将其纳入图中；.gitignore 的否定规则是显式的选择加入。

遥测

CodeGraph 收集匿名使用统计信息——哪些工具和命令被使用，哪些语言被索引——以指导语言和智能体支持工作的方向。绝不收集任何代码、路径、文件或符号名称、查询或 IP 地址；使用情况在本地聚合为每日总数后再发送，接收端点是此仓库中的公共代码，它强制执行文档中列出的字段。安装程序会事先询问；随时关闭：

codegraph telemetry off    # 或：CODEGRAPH_TELEMETRY=0，或 DO_NOT_TRACK=1

TELEMETRY.md 列出了每个字段，以及关闭开关和完整的数据处理说明。

支持的平台

每个版本都为所有三种桌面操作系统（Intel/AMD x64 和 ARM arm64）提供自包含构建（捆绑 Node 运行时——无需编译）：

参见开始使用获取一行安装命令。

支持的智能体

交互式安装程序会自动检测并配置以下每个智能体——连接 MCP 服务器（该服务器会提供自身的使用指南，因此不会写入指令文件）：

• Claude Code
• Cursor
• Codex CLI
• opencode
• Hermes Agent
• Gemini CLI
• Antigravity IDE
• Kiro

支持的语言

实测跨文件覆盖率

影响范围和爆炸半径查询的准确性完全依赖于其背后的依赖图，因此覆盖率是实测的而非声称的。公平覆盖率 = 在每种语言的真实基准仓库中，那些包含符号的源文件中至少有一个已解析的跨文件依赖者（即导入、调用、引用或通过框架约定路由到它们的代码）所占的比例。剩余的部分始终是静态分析的前沿难题（运行时动态分发、反射/DI 容器、框架约定入口点、供应商第三方代码），绝不会通过操纵分母来隐藏。

框架路由也采用相同方式验证，基于每个框架的规范应用：Express 100%、FastAPI 98%、Flask 100%、NestJS 96.8%、Gin 96.5%、Axum 100%、Rocket 93.8%、Vapor 100%、Laravel 92%、Rails 89.6%、React Router 100%——而对于那些依赖约定和反射的框架，则取其静态分析的天花板值：ASP.NET 83.9%、Spring 83.3%、Drupal 78.9%、Play 76.3%、Django 74.1%。SvelteKit、Vue/Nuxt 和 Astro 使用基于文件的路由，因此它们的页面/端点覆盖率即上表中 Svelte/SvelteKit（100%）、Vue/Nuxt（93.5%）和 Astro（93.0%——在两个验证仓库中，每个 src/pages/ 文件都映射到一个路由节点）的数据。

故障排除

“CodeGraph not initialized” — 先在项目目录中运行 codegraph init。

索引速度慢 — 请检查是否排除了 node_modules 和其他大型目录。使用 --quiet 可减少输出开销。

MCP 遇到 “database is locked” — 当前版本不应出现此问题：CodeGraph 自带 Node 运行时，并使用 Node 内置的 node:sqlite 的 WAL 模式，在此模式下并发读取不会阻塞写入。如果仍出现此问题：

• 你使用的是旧版本（0.9 之前的安装）。 重新安装以获取捆绑的运行时——curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh（macOS/Linux），irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex（Windows），或 npm i -g @colbymchenry/codegraph@latest。
• codegraph status 显示 Journal: 不是 wal — 在此文件系统上无法启用 WAL（常见于网络共享和 WSL2 的 /mnt），因此读取可能阻塞写入。请将项目（连同其 .codegraph/ 文件夹）移至本地磁盘。

MCP 服务器无法连接 — 您的代理会自动启动服务器，因此您无需手动启动。请确保项目已初始化和索引（codegraph status），并且 MCP 配置中的路径正确。如果仍无法连接，请重新运行 codegraph install 以重写配置。

缺少符号 — MCP 服务器会在保存时自动同步（等待几秒钟）。如有需要，可手动运行 codegraph sync。请检查文件的语言是否受支持，且文件不在 .gitignore 或默认排除目录（例如 node_modules、dist）内。

在 Windows 和 WSL 之间共享同一个检出目录 — 不要让两者指向同一个 .codegraph/：后台服务器锁和 SQLite 索引与创建它们的操作系统绑定，并且跨 WSL2/Windows 文件系统边界的 SQLite 锁定不可靠。请为每一侧在同一目录树中创建独立的索引，方法是在其中一侧设置 CODEGRAPH_DIR 为不同的名称——例如在 Windows 上设置 CODEGRAPH_DIR=.codegraph-win，让 WSL 使用默认的 .codegraph。CodeGraph 在索引和监视时会跳过任何同级的 .codegraph-* 目录，因此两者不会互相干扰。

星标历史

许可证

MIT