一、项目简介

CodeGraph 是一个本地优先的代码智能工具，专为 AI 编程助手设计。它的核心思想是：

与其让 AI 代理每次都用 grep/glob/Read 重新扫描文件，不如预先建好一张代码知识图谱，让代理直接查图作答。

github地址 ： https://github.com/colbymchenry/codegraph

工作原理

1. 用 tree-sitter 解析代码生成 AST
2. 提取所有符号（函数、类、方法、类型）和边（调用关系、导入、继承）
3. 存入本地 SQLite 数据库（支持 FTS5 全文检索）
4. 通过 MCP 协议、CLI 或 TypeScript 库暴露给 AI 代理

实测性能提升（7 个真实开源项目，每组 4 次运行取中位数）

平均：省 18% 成本 · 少 51% Token · 快 16% · 少 57% 工具调用

核心特点

• 100% 本地运行 — 数据不离机，无需 API Key，无外部服务
• 零配置 — 按文件扩展名自动识别语言
• 20+ 种编程语言 — TS/JS/Python/Go/Rust/Java/C#/PHP/Ruby/C/C++/Swift/Kotlin 等
• 14 种 Web 框架路由识别 — Express/Django/Spring/Laravel/Gin 等
• 自动同步 — 原生 OS 文件监听（FSEvents/inotify/ReadDirectoryChangesW），编辑后 2 秒内更新

二、安装方式

方式一：直接下载（无需 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

每个版本都包含内置 Node.js 运行时，不需要提前安装 Node.js，在 Windows/macOS/Linux 的 x64 和 ARM64 架构上均可运行。

方式二：npm 安装（已有 Node.js）

# 全局安装
npm install -g @colbymchenry/codegraph

MCP添加到 ~/.claude.json （Claude Code）：

{
  "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"
    ]
  }
}

方式三：安装器一键安装

npx @colbymchenry/codegraph

安装器会自动：

• 检测你已安装的 AI 代理（Claude Code、Cursor、Codex CLI、opencode、Hermes Agent、Gemini CLI、Antigravity IDE、Kiro）
• 询问是否把 codegraph 添加到 PATH
• 询问是全局配置（所有项目）还是本地配置（当前项目）
• 写入各代理的 MCP 服务器配置
• 如果选 Claude Code，自动配置权限白名单

非交互模式（适合 CI/脚本）：

codegraph install --target=claude --yes       # 指定代理 (请为 CodeGraph 安装并配置 Claude 模型支持，并且在安装过程中遇到任何确认提示都自动选择‘同意/是’。)

安装完之后要重启 AI 代理（ Claude Code），让其加载 MCP 服务器。

三、快速开始

初始化项目（构建）

安装完之后打开自己的项目目录，使用一行命令搞定项目初始化。

cd your-project
codegraph init -i

init 创建 .codegraph/ 目录； -i （ --index ）同时构建初始索引。全局安装后只需在每个项目执行一次，无需重复安装 MCP 配置。

完成后，只要项目存在 .codegraph/ 目录，AI 代理就会自动使用 CodeGraph 工具。

接下来打开ClaudeCode直接对话即可使用CodeGraph分析项目，示例如下：

请分析一下项目架构是怎样的

卸载方法

codegraph uninstall          # 从所有已配置代理中移除
codegraph uninit             # 移除当前项目的索引（保留代理配置）

四、核心概念

数据流水线

源文件 → tree-sitter 解析（提取节点/边）
            ↓
      引用解析（导入关系、名称匹配、框架模式）
            ↓
      图查询（调用者、被调用者、影响范围）
            ↓
      上下文构建（Markdown/JSON 输出给 AI）

知识图谱结构

节点类型（NodeKind）： file 、 module 、 class 、 struct 、 interface 、 trait 、 protocol 、 function 、 method 、 property 、 field 、 variable 、 constant 、 enum 、 enum_member 、 type_alias 、 namespace 、 parameter 、 import 、 export 、 route 、 component

边类型（EdgeKind）： contains （包含）、 calls （调用）、 imports （导入）、 exports （导出）、 extends （继承）、 implements （实现）、 references （引用）、 type_of （类型关系）、 returns （返回）、 instantiates （实例化）、 overrides （重写）、 decorates （装饰）

动态调度桥接

静态 tree-sitter 解析无法追踪动态调用，CodeGraph 通过合成器（Synthesizer）桥接这些边界：

• 回调/观察者模式
• EventEmitter 事件
• React setState → render （React 重渲染）
• JSX 子组件（ render → 子组件）
• Django ORM 描述符

所有合成边带有 provenance: 'heuristic' 标记及 metadata.synthesizedBy 字段，AI 可以清晰识别。

五、CLI 命令参考

基础命令

codegraph                         # 运行交互式安装器
codegraph install                 # 运行安装器（显式）
codegraph uninstall               # 从代理中移除 CodeGraph

项目管理

# 初始化项目
codegraph init [path]             # 初始化（--index 或 -i 同时建索引）
codegraph uninit [path]           # 移除项目索引（--force 跳过确认）

# 建立/更新索引
codegraph index [path]            # 全量索引（--force 强制重建，--quiet 减少输出）
codegraph sync [path]             # 增量更新（只处理变更的文件）

# 查看状态
codegraph status [path]           # 显示节点/边/文件数量和 SQLite 后端信息

查询命令

# 搜索符号
codegraph query <search>          # 搜索符号（--kind 过滤类型，--limit 限制数量，--json 输出 JSON）

# 示例：
codegraph query UserService --kind class --limit 10
codegraph query handleRequest --json

# 调用关系
codegraph callers <symbol>        # 查找调用该函数的位置（--limit，--json）
codegraph callees <symbol>        # 查找该函数调用了什么（--limit，--json）
codegraph impact <symbol>         # 分析修改该符号会影响哪些代码（--depth，--json）

# 文件结构
codegraph files [path]            # 显示文件结构（--format，--filter，--max-depth，--json）

# 上下文构建
codegraph context <task>          # 为 AI 构建上下文（--format，--max-nodes）

codegraph affected — CI 利器

根据变更文件，追踪依赖关系，找出受影响的测试文件：

codegraph affected src/utils.ts src/api.ts          # 直接传文件名
git diff --name-only | codegraph affected --stdin   # 从 git diff 管道输入
codegraph affected src/auth.ts --filter "e2e/*"     # 自定义测试文件 glob

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 服务器

codegraph serve --mcp
bash1

一般由 AI 代理自动启动，无需手动执行。

六、MCP 工具详解

当 CodeGraph 作为 MCP 服务器运行时，向 AI 代理暴露以下 10 个工具：

codegraph_search — 符号搜索

按名称在整个代码库搜索符号，支持全文检索（FTS5）。

使用场景： 当你知道函数/类的名字但不知道在哪个文件时。

codegraph_context — 上下文构建(建议SubAgent中调用)

基于任务描述构建相关代码上下文，内部组合了 search + node + callers + callees，一次调用完成。

使用场景： 让 AI 理解某个功能区域的全貌。

codegraph_trace — 调用链追踪

追踪两个符号之间的调用路径（“X 是如何到达 Y 的”），每一跳都内联显示函数体，能跨越动态调度边界（回调、React 重渲染、接口实现）——这是 grep 无法做到的。

使用场景： 理解代码流程，例如"请求是如何到达数据库的"。

示例流程（Excalidraw）：
mutateElement → triggerUpdate → [callback] triggerRender
  → [react-render] render → [jsx] StaticCanvas → renderStaticScene

codegraph_callers — 调用者查询

查找哪些地方调用了某个函数。

使用场景： 修改函数前，了解所有调用方以评估影响。

codegraph_callees — 被调用者查询

查找某个函数调用了哪些函数。

使用场景： 理解函数的依赖关系。

codegraph_impact — 影响分析

分析修改某个符号后，会影响哪些代码（BFS 广度优先搜索）。

使用场景： 重构前的安全评估，避免意外破坏其他功能。

codegraph_node — 符号详情

获取某个特定符号的详细信息，可选择附带源代码。

使用场景： 查看函数签名、文档或源码。

codegraph_explore — 多符号探索(建议SubAgent中调用)

一次调用返回多个相关符号的源码（按文件分组）以及它们之间的关系图。

使用场景： 当需要同时理解多个相关符号时，避免多次单独调用。

codegraph_files — 文件结构

获取已索引的文件结构（比文件系统扫描快得多）。

使用场景： 快速了解项目文件布局。

codegraph_status — 索引状态

查看索引健康状况和统计数据，包括待同步文件列表。

使用场景： 确认索引是否是最新的。

工具选用指南

AI 代理会根据任务自动选择工具，以下是选择逻辑：

七、支持的 编程语言

语言支持完全自动，根据文件扩展名识别， 无需任何配置 。

八、框架路由识别

CodeGraph 能识别 Web 框架的路由文件，并将 URL 模式与处理函数关联。查询控制器的调用者时，可以看到绑定它的 URL 路由。

九、iOS/React Native 混合开发支持

真实的 iOS 和 React Native 项目往往跨越多种语言，静态解析在每个语言边界处断裂。CodeGraph 通过桥接合成器跨语言连接这些调用链。

所有合成边带有 provenance: 'heuristic' 标记， metadata.synthesizedBy 字段指明桥接类型（如 swift-objc-bridge 、 rn-event-channel ）。

十、自动同步机制

CodeGraph 提供三层自动同步，确保 AI 代理永远不会读取到过期数据：

第一层：文件监听 + 防抖自动同步

codegraph serve --mcp 启动时会开启原生文件监听：

• macOS → FSEvents
• Linux → inotify
• Windows → ReadDirectoryChangesW

每次源文件创建/修改/删除后，经过 2000ms 防抖窗口合并批量操作，自动触发增量同步。

代理修改 src/Widget.ts
  → 监听器触发（通常 <100ms）
  → 2000ms 防抖等待
  → 同步运行，Widget.ts 的节点和边进入索引
  → 下一次代理查询即可看到更新

调整防抖时间：

CODEGRAPH_WATCH_DEBOUNCE_MS=5000   # 设为 5 秒，适合批量写入场景

范围限制： [100ms, 60s]

第二层：文件过期提示横幅

在 2 秒防抖窗口内，如果 MCP 工具响应引用了还未重新索引的文件，响应头部会显示警告：

⚠️ 以下文件在上次索引后被修改，codegraph 的相关记录可能已过期：
  - src/Widget.ts（800ms 前修改，待同步）
请直接 Read 这些文件以获取最新内容。
以下其余内容是最新的。

AI 代理会读取这个提示并直接 Read 对应文件，避免静默地使用过期数据。

第三层：连接时追赶同步

每次 MCP 服务器（重新）连接时，CodeGraph 先做一次快速文件系统对比（ size + mtime 预筛，再做内容哈希），将未在上次会话中同步的变更全部吸收，再响应第一个查询。

手动同步的适用场景

极少数情况下才需要手动运行 codegraph sync ：

• 运行在沙箱环境，文件监听被禁用
• 设置了 CODEGRAPH_NO_DAEMON=1
• CI 脚本中，需要在脚本开始前确保索引是最新的