CodeGraph — 语义代码智能

CodeGraph 是基于 tree-sitter 的本地代码知识图谱工具，为 AI 编码代理（Claude Code、Cursor、Codex、Gemini 等）提供符号关系、调用图和代码结构的即时查询能力。

核心收益：平均节省 ~16% 成本、~58% 减少工具调用、~47% 减少 token 消耗、~22% 加速响应。

100% 本地 — 无数据离开机器，无 API 密钥，无外部服务，仅 SQLite 数据库。

Capability Boundaries

✅ Strong Suits

代码结构查询 — "X 如何工作"、"X 如何到达 Y"
符号搜索与调用链追踪 — 查找函数/类的调用者与被调用者
变更影响分析 — 修改某符号前分析影响范围（blast radius）
框架路由识别 — Django/Express/NestJS/Spring/Gin 等 14 个框架的路由绑定
跨语言桥接 — iOS（Swift↔ObjC）、React Native（JS↔原生）、Expo Modules
自动同步 — 文件监听器 + 防抖自动同步，索引随代码实时更新
全文搜索 — 基于 FTS5 的符号名即时搜索
受影响测试文件追踪 — codegraph affected 溯源变更影响的测试文件

⚠️ Requirements

项目需运行 codegraph init -i 初始化知识图谱索引
MCP 服务器需通过 codegraph install 配置到目标 Agent
配置后需重启 Agent 才能加载 MCP 服务器
首次索引可能需要几分钟（取决于代码库大小）

❌ Out of Scope（附替代方案）

实时调试 / 运行时动态分析 → 使用调试器（如 GDB、Chrome DevTools）
非文件系统项目（如远程仓库未检出）→ 先 clone 到本地
代码编辑/生成 → 使用 Agent 自身的编辑能力
CI/CD 流水线管理 → 使用专用 CI 工具

When to Use This Skill

Use this skill when the agent needs to:

理解代码库架构："X 如何工作"、"请求如何到达数据库"
追踪符号依赖："谁调用了 X"、"X 调用了谁"
分析变更影响："修改 X 会影响什么"
查找调用链："从 A 到 B 的完整路径"
审查代码结构：获取项目文件结构、符号索引
确定受影响的测试文件：codegraph affected

Data Privacy

CodeGraph 不收集、存储或传输任何用户数据。所有索引存储在项目本地的 .codegraph/ 目录中，SQLite 数据库不会离开你的机器。无 API 密钥，无外部服务。

How It Works

Agent → CodeGraph MCP Server (explore/search/callers/callees/impact/node)
         → SQLite 知识图谱 (符号 · 边 · 文件 · FTS5)

Extraction — tree-sitter 解析源代码为 AST，提取节点和边
Storage — 存入本地 SQLite 数据库（.codegraph/codegraph.db），支持 FTS5
Resolution — 解析引用关系：调用→定义、导入→源文件、框架路由
Auto-Sync — 原生 OS 文件事件监听 + 防抖同步（默认 2s），索引实时更新

Quick Start

# Step 1: 安装 CLI（无需 Node.js）
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh
# Step 2: 配置 Agent
codegraph install
# Step 3: 初始化项目
cd your-project
codegraph init -i

Workflow

Step 1. 初始化项目 — 确认 .codegraph/ 存在，若不存在则运行 codegraph init -i

Step 2. 选择合适工具 — 根据查询意图选择 MCP 工具（见工具选择矩阵）

Step 3. 执行查询 — 调用 MCP 工具获取结果。关键约束：

绝不在不熟悉的 API 或不确定的符号关系上胡编乱造；如果 CodeGraph 返回空结果或无法确认，直接告诉用户"未找到该符号/关系"，不强加虚构信息
信息不足时：先输出基于已有信息的假设版本，再列出具体缺少的 N 项内容，引导用户补充。禁止笼统提示"请提供更多信息"

Step 4. 处理结果 — 将返回的符号源码视为已读，无需再用 grep/read 验证

Step 5. 检查时效性 — 编辑文件后检查响应中的 ⚠️ staleness banner，若有则直接 Read 对应文件

MCP 工具选择矩阵

| 查询意图 | 推荐工具 | 说明 | |---------|---------|------| | "X 如何工作" / 流程追踪 | codegraph_explore | 首选。一次调用返回源码、关系图和影响范围 | | 查找符号位置 | codegraph_search | 按名称搜索 | | 谁调用了 X | codegraph_callers | 查找调用者 | | X 调用了谁 | codegraph_callees | 查找被调用者 | | 修改 X 的影响 | codegraph_impact | 影响范围分析 | | 获取符号详情 | codegraph_node | 完整源码和元数据 | | 项目文件结构 | codegraph_files | 已索引文件列表 | | 索引健康状态 | codegraph_status | 统计和健康度 |

各工具参数详解见 references/mcp-tools.md

CLI 命令速查

codegraph install/uninstall         # 安装/移除 Agent 配置
codegraph init/uninit [path]        # 初始化/移除项目索引
codegraph index/sync [path]         # 索引/增量同步
codegraph status/query/files        # 状态查询
codegraph callers/callees/impact    # 调用链/影响分析
codegraph affected [files...]       # 受影响测试文件
codegraph serve --mcp               # 启动 MCP 服务器
codegraph upgrade [version]         # 升级

完整参考见 references/cli-reference.md

安装速查

自动安装（推荐）：

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

手动配置 Claude Code 见 references/installation.md

Gotchas

先连接 MCP 服务器 — codegraph install 仅配置 Agent，不会自动启动 MCP；需重启 Agent 才能加载
codegraph init -i 是必需的 — 每个项目首次使用前必须初始化索引，否则所有 MCP 工具失败
防抖窗口（2s）内的数据可能过时 — 编辑后立即查询可能返回旧数据，检查 ⚠️ banner
WSL/Windows 共享检出 — 不要共享同一 .codegraph/，使用 CODEGRAPH_DIR 区分
MCP 服务器自行交付使用指南 — 无需手动编辑 CLAUDE.md，指南通过 MCP initialize 自动交付
排除目录 — node_modules、dist、build 等默认排除，通过 .gitignore 管理
信息不足时不要笼统提问 — 先输出假设版本，再列具体缺少项（见 Workflow Step 3 模板）

Quick Fixes

| 问题 | 解决 | |------|------| | "not initialized" | 运行 codegraph init -i | | 索引慢 | 确认 node_modules 等已被排除 | | database is locked | 升级到最新版；检查 Journal 是否为 wal | | 符号缺失 | 等待自动同步或 codegraph sync；检查语言是否支持 |

详见 references/troubleshooting.md

FAQ

Q: CodeGraph 和 grep/find 有什么区别？ A: CodeGraph 构建完整的符号关系图谱，理解调用链、继承关系和框架路由；grep 只能做文本匹配，无法理解代码语义。

Q: 索引会占用多少空间？ A: 取决于代码库大小。典型项目（~1000 文件）约几 MB；大型项目（~10k 文件）约几十 MB。

Q: 支持 monorepo 吗？ A: 支持。在 monorepo 的各子项目目录中分别运行 codegraph init -i 即可。

Q: 如何更新索引？ A: MCP 服务器运行时自动同步。手动可运行 codegraph sync 增量更新或 codegraph index --force 重建。

Q: 可以离线使用吗？ A: 完全离线。所有数据存储在本地 SQLite 数据库中，无任何网络请求。

Q: 如何卸载？ A: 运行 codegraph uninstall 移除所有 Agent 配置；codegraph uninit 移除项目索引。

Q: 我的项目是 Java/Python/Rust，CodeGraph 支持吗？ A: 支持 20+ 语言，包括 Java、Python、Rust、Go、TypeScript 等。完整列表见 references/supported-languages.md

Q: 框架路由识别有什么用？ A: CodeGraph 能自动识别 Django、Express、Spring、Gin 等 14 个 Web 框架的路由绑定，将 URL 路径直接关联到处理器函数，方便追踪请求流转。

Q: 跨语言桥接覆盖哪些场景？ A: 支持 Swift↔ObjC 自动桥接、React Native 旧桥/TurboModules/Fabric、Expo Modules、以及原生→JS 事件通道。

Q: 索引失败或卡住怎么办？ A: 运行 codegraph status 查看状态；检查是否有大文件（>1MB 被跳过）；确认目录不在排除列表中；可尝试 codegraph index --force 重建。

Official Sources

References

Audience

| 用户类型 | 使用方式 | |---------|---------| | 新用户 | 通过 Quick Start 三步上手，使用 codegraph_explore 解答代码问题 | | 高级用户 | 组合使用 callers/callees/impact 进行深度架构分析 | | CI/维护者 | 使用 codegraph affected 追踪变更影响的测试文件 |