CodeGraph 中文入门手册

CodeGraph 是一个本地运行的代码知识图库（Knowledge Graph）工具，它会将代码仓库解析成图结构，并通过 MCP（Model Context Protocol）提供给 Claude Code、Codex CLI、Cursor、OpenCode 等 AI 编程工具使用。

官方仓库：

https://github.com/colbymchenry/codegraph

官方文档：

https://colbymchenry.github.io/codegraph/

---

一、CodeGraph 是什么

传统 AI 编程助手分析大型项目时，通常会：

grep
↓
搜索文件
↓
读取文件
↓
继续搜索
↓
继续读取

大量 Token 都浪费在「寻找代码」上。

CodeGraph 的思路是：

源代码
 ↓
Tree-sitter解析
 ↓
知识图谱
 ↓
SQLite存储
 ↓
MCP服务
 ↓
AI助手查询

AI 不再需要反复扫描整个仓库，而是直接查询：

• 某个方法在哪里定义
• 谁调用了这个方法
• 哪些类继承了这个接口
• 修改某个函数会影响哪些模块

官方测试数据显示，在大型项目中：

• Token 消耗减少约 57%
• Tool Call 减少约 71%
• 响应速度提升约 46%
• 成本降低约 35%

---

二、核心架构

1. 代码解析

CodeGraph 使用 Tree-sitter 解析代码：

Java
Python
Go
TypeScript
JavaScript
Rust
...

支持 20+ 语言。

---

2. 构建图结构

例如：

@RestController
public class UserController {

    @Autowired
    private UserService userService;

    @GetMapping("/users")
    public List<User> list() {
        return userService.findAll();
    }
}

会生成类似：

UserController
    │
    ▼
list()
    │ calls
    ▼
UserService.findAll()

---

3. 存储

默认存储：

.codegraph/
├── codegraph.db

使用 SQLite + FTS5 全文索引。

---

4. MCP 服务

向 AI Agent 暴露查询能力：

Claude Code
Cursor
Codex CLI
OpenCode
Hermes
Gemini CLI

都可以直接查询图谱。

---

三、安装方式

方法1：npx

如果已安装 Node.js：

npx @colbymchenry/codegraph

安装器会自动：

• 检测 Claude Code
• 检测 Cursor
• 检测 Codex CLI
• 配置 MCP
• 添加权限
• 初始化项目

---

方法2：全局安装

npm install -g @colbymchenry/codegraph

然后：

codegraph install

---

方法3：Mac/Linux 一键安装

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

---

四、新手最快上手（Claude Code）

假设你已经安装：

claude

并且有一个 Spring Boot 项目：

demo-project
 ├── src
 ├── pom.xml
 └── ...

---

第一步：安装 CodeGraph

npm install -g @colbymchenry/codegraph
codegraph install

此时 codegraph 会自定检测出你当前环境下已经安装的agent信息，选择你希望的agent：

◆  Which agents should CodeGraph configure?
│  ◼ Claude Code (detected)
│  ◼ Cursor (detected)
│  ◼ Codex CLI (detected) — global only
│  ◼ opencode (detected)
│  ◻ Hermes Agent (not found) — global only
│  ◻ Gemini CLI (detected)
│  ◻ Antigravity IDE (detected) — global only
│  ◻ Kiro (not found)
└

选择(此时实际上就是为这些agent配置mcp server)：

◆  Install the codegraph CLI on your PATH? (Required so agents can launch the MCP 
│  server)
│  ● Yes / ○ No

可以选择全局安装，也可以只为当前项目安装

◆  Apply agent configs to all your projects, or just this one?
│  ● All projects (~/.claude, ~/.cursor, etc.)
│  ○ Just this project

是否 自动允许CodeGraph命令？（跳过Claude Code中的权限提示）

◆  Auto-allow CodeGraph commands? (Skips permission prompts in Claude Code)
│  ● Yes / ○ No
└

安装完成。

◆  Claude Code: Updated ~/.claude.json
│
◆  Claude Code: Updated ~/.claude/settings.json
│
◆  Cursor: Updated ~/.cursor/mcp.json
│
●  Cursor: Restart Cursor for MCP changes to take effect.
│
◆  Codex CLI: Updated ~/.codex/config.toml
│
◆  opencode: Updated ~/.config/opencode/opencode.json
│
◇  Quick start ───────╮
│                     │
│  cd your-project    │
│  codegraph init -i  │
│                     │
├─────────────────────╯
│
└  Done! Restart your agents to use CodeGraph.

---

第二步：进入项目

cd demo-project

---

第三步：构建索引

codegraph init -i

生成：

.codegraph/
 ├── codegraph.db
 └── ...

---

第四步：重启 Claude Code

claude

或重新打开终端。

因为 MCP Server 需要重新加载。

---

第五步：开始提问

例如：

这个项目的Controller调用链是什么？

或：

UserService.findById被哪些地方调用？

或：

修改OrderEntity会影响哪些模块？

Claude 会优先查询 CodeGraph，而不是暴力扫描整个项目。

---

五、常用命令

初始化项目

codegraph init -i

构建知识图谱。

---

查看状态

codegraph status

查看：

数据库状态
索引数量
同步状态
SQLite驱动

---

安装

codegraph install

---

卸载

codegraph uninstall

删除 MCP 配置。

---

删除项目索引

codegraph uninit

删除：

.codegraph

---

六、适合哪些项目

效果最明显：

Spring Boot

Controller
 ↓
Service
 ↓
Repository

调用链复杂。

---

微服务

user-service
order-service
payment-service

跨模块调用分析。

---

大型前端

React
Next.js
Vue

组件依赖分析。

---

Kubernetes Operator

例如：

Reconcile()
 ↓
Client.Get()
 ↓
Update()
 ↓
Status().Update()

CodeGraph 对这种调用关系分析非常有价值。

---

七、与 Claude Code 配合的最佳实践

不要问：

帮我看看这个项目

要问：

利用 CodeGraph 分析：

1. 核心领域模型
2. Service调用关系
3. Controller入口
4. 数据库访问路径

或者：

使用 CodeGraph 找出：

OrderService.createOrder()
的完整调用链

或者：

使用 CodeGraph 分析：
如果删除 UserRepository.findByEmail()
会影响哪些代码

这样才能充分利用图谱能力。

---

八、CodeGraph 与普通 MCP 的区别

方案	工作方式
Filesystem MCP	读取文件
Git MCP	查询仓库
Database MCP	查询数据库
CodeGraph MCP	查询代码关系图

CodeGraph 更像：

Neo4j
+
Tree-sitter
+
MCP

专门针对代码分析优化。

---

九、适不适合你？

结合以下使用场景：

• Spring Boot
• Kubernetes
• Java Operator
• 多模块项目
• Claude Code
• Codex CLI

CodeGraph 非常值得安装。

尤其是当项目超过：

5万行代码
10+模块
多人协作

之后，Claude/Codex 对代码结构的理解能力会明显提升，因为它们能直接查询调用图，而不是不停地 grep 和 read 文件。

---

十、总结

CodeGraph 的核心价值在于：

1. 将代码转化为知识图谱
2. 通过 MCP 提供给 AI Agent
3. 减少 Token 消耗
4. 提高大型项目分析能力
5. 提升 Claude Code、Codex CLI、Cursor 等工具的代码理解能力

对于以下开发者尤其有价值：

• Java / Spring Boot 开发者
• Kubernetes Operator 开发者
• 微服务架构团队
• 大型前端项目团队
• 使用 Claude Code、Codex CLI、Cursor 的 AI 编程用户

推荐安装后优先在大型项目中使用，效果最明显。