一、CodeGraph 是什么？

CodeGraph 是一个本地优先的代码智能库 + CLI + MCP 服务器，由 @colbymchenry 开发并在 GitHub 开源（github.com/colbymchenry/codegraph），截至目前已斩获 20k+ Star。

它利用 tree-sitter 解析代码库，将符号（函数、类、方法等）、调用边（调用、继承、导入关系）和文件结构存储于 SQLite + FTS5 数据库中，并通过 MCP（Model Context Protocol） 向 AI 编程助手暴露知识图谱查询能力。

简单来说：

• 没有 CodeGraph 的 AI = 新人入职，靠 Ctrl+F 逐文件 grep 找代码

• 有 CodeGraph 的 AI = 拥有完整组织架构图的老员工，直接知道找谁

它兼容的主流 AI 编程工具包括：Claude Code、Cursor、Codex CLI、OpenCode、Gemini、Kiro、Hermes Agent 等 8+ 款工具。

二、为什么需要 CodeGraph？

当你使用 AI 编程助手处理大型代码库时，一定经历过这种痛苦：

1. Token 爆炸 — AI 每次对话都反复扫描文件，一个几千行的项目光读取就消耗大量 Token

2. 响应缓慢 — AI 要逐文件 grep 才能理清调用关系，动辄等待数分钟

3. 上下文混乱 — 大量无关文件内容塞满上下文窗口，AI 回答质量下降

4. 隐私风险 — 代码全部发送到云端 API 进行分析

CodeGraph 的核心思路：与其让 AI 每次都去扫描文件，不如提前建好索引。AI 查代码时，直接查索引——快到飞起。

三、核心优势

根据 7 个真实开源项目（VS Code、Excalidraw、Django、Tokio、OkHttp、Gin、Alamofire）的实测数据：

其他亮点：

• 100% 本地运行：所有操作在本地完成，代码永不外泄，无需 API 密钥

• 多语言支持：基于 tree-sitter，支持 JavaScript、TypeScript、Python、Rust、Go、Java、C、C++、C#、Swift、Kotlin 等主流语言

• 增量索引：支持 watch 模式，文件变化时自动更新索引

• 轻量存储：索引数据存储在本地 SQLite 数据库，占用空间极小

四、安装教程

4.1 环境要求

• Node.js >= 18

• npm / pnpm / yarn 任一包管理器

4.2 全局安装（推荐）

在终端中执行以下命令：

# 使用 npm
npm install -g @colbymchenry/codegraph

# 或使用 pnpm（速度更快）
pnpm add -g @colbymchenry/codegraph

4.3 零安装方式（npx 一次性使用）

npx @colbymchenry/codegraph

4.4 验证安装

codegraph --version
# 输出类似：codegraph v0.9.8 即表示安装成功

4.5 交互式安装（自动配置 MCP）

CodeGraph 还提供了交互式安装命令，自动检测你的 AI 工具并完成 MCP 配置：

# 交互式安装
codegraph install

# 自动检测并接受默认值
codegraph install --yes

# 指定目标工具
codegraph install --target=cursor,claude --yes

五、使用方法

5.1 构建代码索引

进入你的项目根目录，执行 build 命令：

# 进入项目目录
cd /path/to/your/project

# 构建代码知识图谱
codegraph build

# 索引数据存储在项目目录下的 .codegraph/codegraph.db

build 命令会执行以下操作：

1. 扫描整个项目，用 tree-sitter 解析所有源代码文件

2. 提取符号（函数、类、方法等）和关系（调用、导入、继承等）

3. 存入 .codegraph/codegraph.db SQLite 数据库

4. 自动配置项目级的 Agent 指引文件

5.2 实时监控文件变化（增量更新）

# 启动文件监控，代码变更时自动更新索引
codegraph watch

5.3 配置 MCP Server

要让 AI 编程工具（如 Claude Code、Cursor）使用 CodeGraph，需要配置 MCP Server。在项目根目录创建或编辑 mcp.json 文件：

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

Claude Code 配置方式：编辑 ~/.claude.json 文件，添加如下内容：

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

Cursor / Trae 配置方式：在 IDE 中打开设置 → MCP Servers → 添加 codegraph，或使用快捷键 Ctrl+Shift+P → Configure MCP Servers。

5.4 核心 CLI 命令

5.5 典型工作流程

日常使用中，推荐以下工作流程：

1. 初始化项目：codegraph build 构建索引

2. 启动监控：codegraph watch 保持索引同步

3. 配置 MCP：让 AI 工具连接到 CodeGraph

4. 正常使用 AI：在 Claude Code / Cursor 中提问，AI 会自动调用 codegraph 工具查询代码结构

当 AI 需要理解代码时，它不再盲目 grep 扫描，而是通过 MCP 协议调用 CodeGraph 的查询接口，以亚毫秒级速度获取预索引的结构化数据。

5.6 自定义索引配置

在项目根目录创建 codegraph.config.json 文件，可自定义索引范围：

{
  "include": ["src/**/*.ts", "src/**/*.js"],
  "exclude": ["**/test/**", "**/node_modules/**", "**/build/**"]
}

六、使用效果对比

以 VS Code 源码（约 10k 文件）为例，使用 CodeGraph 前后的对比：

项目越大，效果越明显。对于超过 1 万文件的大型仓库，工具调用次数可减少 80%+。

七、常见问题 FAQ

Q：安装后提示"不是内部命令"怎么办？

A：关闭当前终端窗口，重新打开一个新终端，确保 PATH 已生效。也可以尝试 npm root -g 检查全局安装路径。

Q：支持哪些编程语言？

A：基于 tree-sitter，支持 JavaScript、TypeScript、Python、Rust、Go、Java、C、C++、C#、Swift、Kotlin、Ruby、PHP 等主流语言。

Q：索引数据会上传到云端吗？

A：不会。所有数据 100% 存储在本地 .codegraph/codegraph.db 文件中，无需联网，代码永不外泄。

Q：多项目如何管理？

A：每个项目独立执行 codegraph build，在各自目录下启动 AI 工具即可自动隔离，互不干扰。

八、总结

CodeGraph 是当前最成熟的本地代码知识图谱引擎，它解决了一个非常具体的痛点：AI 编程 Agent 需要的不是更多上下文，而是一张提前画好的代码地图。

如果你经常使用 Claude Code、Cursor 等 AI 工具开发中大型项目，CodeGraph 几乎是必装工具。安装简单、零成本、100% 本地运行，却能带来 Token 消耗降低 57%、工具调用减少 70% 的显著提升。

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

npm 包名：@colbymchenry/codegraph