codegraph

CodeGraph — 语义代码智能

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

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

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

Capability Boundaries

✅ Strong Suits

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

⚠️ Requirements

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

❌ Out of Scope（附替代方案）

1. 实时调试 / 运行时动态分析 → 使用调试器（如 GDB、Chrome DevTools）
2. 非文件系统项目（如远程仓库未检出）→ 先 clone 到本地
3. 代码编辑/生成 → 使用 Agent 自身的编辑能力
4. 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)

1. Extraction — tree-sitter 解析源代码为 AST，提取节点和边
2. Storage — 存入本地 SQLite 数据库（.codegraph/codegraph.db），支持 FTS5
3. Resolution — 解析引用关系：调用→定义、导入→源文件、框架路由
4. 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