什么是 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 编程助手 |
快速安装
一键安装（推荐，无需 Node.js）
CodeGraph 自带运行时，不需要预先安装 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 安装
如果你已有 Node.js 环境：
# 零安装直接使用
npx @colbymchenry/codegraph
# 或全局安装
npm i -g @colbymchenry/codegraph
初始化项目
安装完成后，在项目目录下运行交互式安装器：
npx @colbymchenry/codegraph
安装器会依次：
- 检测你已安装的 Agent（Claude Code、Cursor 等）
- 询问是否将 codegraph 添加到 PATH
- 选择配置作用范围（全局 or 本项目）
- 自动写入各 Agent 的 MCP 服务器配置
- 初始化当前项目索引
非交互模式（脚本/CI 场景）
# 自动检测 Agent，全局安装
codegraph install --yes
# 指定目标 Agent
codegraph install --target=cursor,claude --yes
# 项目级安装
codegraph install --target=auto --location=local
# 仅打印配置片段，不写文件
codegraph install --print-config codex
建立代码索引
配置好 Agent 后，需要对项目建立知识图谱索引：
# 首次建立全量索引
codegraph index
# 强制重建（忽略缓存）
codegraph index --force
# 安静模式
codegraph index --quiet
索引会在项目根目录生成 .codegraph/ 文件夹，里面包含了项目的符号表、调用关系图、文件结构等信息。
日常开发中，修改代码后增量更新即可：
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 可以自动找出需要重新运行的测试文件：
# 直接传入文件
codegraph affected src/utils.ts src/api.ts
# 配合 git diff
git diff --name-only | codegraph affected --stdin
# 自定义测试匹配模式
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 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
全局安装后编辑 ~/.claude.json：
{
"mcpServers": {
"codegraph": {
"type": "stdio",
"command": "codegraph",
"args": ["serve", "--mcp"]
}
}
}
免确认配置（~/.claude/settings.json）：
{
"permissions": {
"allow": [
"mcp__codegraph__codegraph_search",
"mcp__codegraph__codegraph_context",
"mcp__codegraph__codegraph_callers",
"mcp__codegraph__codegraph_callees",
"mcp__codegraph__codegraph_impact",
"mcp__codegraph__codegraph_node",
"mcp__codegraph__codegraph_status",
"mcp__codegraph__codegraph_files"
]
}
}
实际效果对比
根据社区实测，在约 10 万行代码的项目中使用 CodeGraph 前后的对比：
| 指标 | 无 CodeGraph | 使用 CodeGraph |
|---|---|---|
| 定位函数的平均工具调用 | 5-8 次 | 1-2 次 |
| Token 消耗 | 较高 | 降低约 25% |
| 修改后测试发现 | 手动 grep | 自动追踪依赖 |
| 调用链路追踪 | 多次 grep | 一次 trace 搞定 |
最佳实践
- 项目初始化时立即建索引 — 越早建立，Agent 越早受益
- 定期 codegraph sync — 集成到 Git hooks 中自动执行
- 使用 --json 输出 — 配合 jq 进行自动化处理
- 配合 codegraph context 编写 Agent 指令 — 在 CLAUDE.md 中引用上下文
- 将 codegraph affected 集成到 CI — 只运行受影响的测试
总结
CodeGraph 解决了 AI 编程代理在大型代码库中"盲目扫描"的痛点。通过一次索引、多次查询的模式，它将 Agent 理解代码的效率提升了数倍。对于使用 Claude Code、Cursor、Codex 等 AI 编程工具的开发者来说，CodeGraph 是一个值得安装的得力助手。
项目地址：https://github.com/colbymchenry/codegraph 官方文档：https://colbymchenry.github.io/codegraph/
评论