CodeGraph 使用指南：为 AI 编程代理打造代码知识图谱，告别盲目扫描

CodeGraph 开源工具为代码仓库建预索引知识图谱，助 AI 编程代理减少 62% 工具调用、省 25% Token。

2026年6月2日3 分钟阅读

什么是 CodeGraph？

CodeGraph 是由独立开发者 Colby McHenry 创建的开源项目（GitHub 36.9k+ Stars），是一个预索引的代码知识图谱工具。它的核心思路很直接：既然 AI 编程代理每次都要从头扫描文件来理解代码，那为什么不提前把代码的符号、函数、类以及调用关系建好索引，让 Agent 直接查询呢？

核心优势

减少约 62% 的工具调用 — Agent 不再需要反复 grep、Read 文件来定位代码
节省约 25% 的 Token 消耗 — 查询知识图谱比扫描文件树轻量得多
100% 本地运行 — 代码不会离开你的机器
支持 19+ 种编程语言 — 涵盖主流语言和框架
增量更新 — 编辑代码后只需 sync，不必全量重建

支持的 Agent

CodeGraph 通过 MCP（Model Context Protocol）协议与以下 AI 编程代理集成：

Agent	说明
Claude Code	Anthropic 官方 CLI 编程助手
Cursor	基于 VS Code 的 AI IDE
Codex CLI	OpenAI 的终端编程代理
Gemini CLI	Google 的 AI 命令行工具
OpenCode	开源终端 AI 编程工具
Hermes Agent	通用 AI 代理框架
Antigravity IDE	AI 原生 IDE
Kiro	AI 编程助手

快速安装

# 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（已有 Node.js 环境）
npx @colbymchenry/codegraph
npm i -g @colbymchenry/codegraph

初始化项目

npx @colbymchenry/codegraph

# 非交互模式
codegraph install --yes
codegraph install --target=cursor,claude --yes
codegraph install --target=auto --location=local
codegraph install --print-config codex

建立代码索引

codegraph index        # 全量索引
codegraph index --force # 强制重建
codegraph sync          # 增量更新
codegraph status        # 查看状态

CLI 命令大全

命令	用途
codegraph init [path]	在项目中初始化
codegraph uninit [path]	移除项目中的 CodeGraph
codegraph index [path]	建立全量索引
codegraph sync [path]	增量更新索引
codegraph status [path]	查看索引统计
codegraph query <关键词>	搜索符号
codegraph files [path]	查看文件结构
codegraph context <任务>	为 AI 构建上下文
codegraph callers <符号>	查找调用者
codegraph callees <符号>	查找被调用者
codegraph impact <符号>	分析修改影响范围
codegraph affected [文件...]	找出受影响的测试文件
codegraph serve --mcp	启动 MCP 服务器

实战：查找受影响测试

codegraph affected src/utils.ts src/api.ts
git diff --name-only | codegraph affected --stdin
codegraph affected src/auth.ts --filter "e2e/*"

MCP 工具详解

以 MCP 服务器模式运行时（codegraph serve --mcp），CodeGraph 向 Agent 暴露以下工具：

工具	用途
codegraph_search	按名称搜索符号
codegraph_context	为任务构建相关代码上下文
codegraph_trace	追踪两个符号之间的调用路径
codegraph_callers	查找调用者
codegraph_callees	查找被调用者
codegraph_impact	分析修改影响范围
codegraph_node	获取符号详细信息（含源码）
codegraph_explore	一次返回多个符号源码+关系图
codegraph_files	获取文件结构
codegraph_status	检查索引健康状况

手动配置 MCP

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

实际效果对比

指标	无 CodeGraph	使用 CodeGraph
定位函数的平均工具调用	5-8 次	1-2 次
Token 消耗	较高	降低约 25%
修改后测试发现	手动 grep	自动追踪依赖
调用链路追踪	多次 grep	一次 trace 搞定