CodeGraph AI 工具代码开发利器

一、CodeGraph 是什么？

CodeGraph 是一个本地代码知识图谱工具，用来增强 Claude Code、Cursor、Codex、Gemini 等 AI 编程助手的代码理解能力。

它会扫描你的项目代码，生成一个本地 .codegraph/ 索引，让 AI 不再靠反复 grep、glob、逐个文件读取来理解项目，而是可以一次查询拿到相关代码、调用链和影响范围。

简单理解：

没有 CodeGraph：AI 一个文件一个文件找代码
有 CodeGraph：AI 直接查本地代码图谱

二、核心功能总结

1. 语义代码理解

CodeGraph 会解析项目中的函数、类、方法、调用关系、依赖关系等信息，并生成本地知识图谱。

AI 可以通过 CodeGraph 快速理解：

某个函数在哪里定义
谁调用了这个函数
这个函数又调用了谁
一次修改可能影响哪些地方
一个业务流程经过哪些代码

三、减少 AI 工具调用

普通 AI 编程助手理解代码时，通常会反复执行：

grep
glob
Read

CodeGraph 可以让 AI 一次查询就拿到精准上下文，从而减少工具调用次数，提高回答速度。

官方 README 中提到，CodeGraph 在多个开源项目测试中可以减少工具调用、减少文件读取，并提升回答速度。

四、本地运行，不上传代码

CodeGraph 的索引保存在本地项目目录中：

.codegraph/

数据存储在本地 SQLite 数据库中，不需要 API Key，也不会把代码上传到外部服务。

适合对代码隐私有要求的项目使用。

五、支持的 AI 工具

CodeGraph 支持配置到多个 AI 编程工具中，包括：

Claude Code
Cursor
Codex CLI
opencode
Hermes Agent
Gemini CLI
Antigravity IDE
Kiro

配置后，这些工具可以通过 MCP 或命令行方式使用 CodeGraph。

六、支持的语言

CodeGraph 支持 20 多种语言，包括：

TypeScript
JavaScript
Python
Go
Rust
Java
C#
PHP
Ruby
C
C++
Objective-C
Swift
Kotlin
Scala
Dart
Lua
R
Svelte
Vue
Astro
Liquid
Pascal / Delphi

七、支持的框架路由识别

CodeGraph 可以识别多种 Web 框架的路由，并把 URL 路径和处理函数关联起来。

支持的框架包括：

Django
Flask
FastAPI
Express
NestJS
Laravel
Drupal
Rails
Spring
Play
Gin
chi
gorilla / mux
Axum
actix
Rocket
ASP.NET
Vapor
React Router
SvelteKit
Vue Router
Nuxt
Astro

这对排查“某个接口请求最终执行了哪些代码”很有用。

八、适合什么场景？

CodeGraph 适合这些场景：

项目代码量比较大
AI 经常需要理解复杂调用链
想减少 AI 反复搜索文件的时间
想分析改动影响范围
想让 Claude Code、Cursor 等工具更快理解项目
想保持代码分析在本地完成

九、安装 CodeGraph

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

使用 npm 安装

如果你已经安装了 Node.js，也可以使用 npm：

npm i -g @colbymchenry/codegraph

安装完成后，建议重新打开一个终端，确保 codegraph 命令可以被识别。

十、配置 AI 工具

安装 CLI 后，执行：

codegraph install

这个命令会自动检测你电脑上已安装的 AI 工具，并帮你配置 CodeGraph。

注意：

codegraph install 只是配置 AI 工具，不会给项目建立索引。

也就是说，安装和配置完成后，还需要进入具体项目执行 codegraph init。

十一、初始化项目

进入你的项目目录：

cd your-project

执行：

codegraph init

这个命令会做两件事：

创建 .codegraph/ 目录
扫描当前项目并建立代码图谱索引

完成后，当前项目就可以被 CodeGraph 分析了。

十二、基本使用流程

完整流程如下：

codegraph install
cd your-project
codegraph init

然后重新启动你的 AI 编程工具，例如 Claude Code 或 Cursor。

之后，当你问 AI 和代码结构相关的问题时，AI 就可以调用 CodeGraph。

十三、常用命令

1. 安装或配置

codegraph install

配置 AI 工具。

2. 卸载配置

codegraph uninstall

移除 CodeGraph 写入到 AI 工具中的配置。

3. 初始化项目

codegraph init

初始化当前项目并建立索引。

4. 移除项目索引

codegraph uninit

移除当前项目的 CodeGraph 配置和索引。

5. 重新完整索引

codegraph index

重新扫描整个项目。

6. 增量同步索引

codegraph sync

同步最近修改的文件。

通常不需要手动执行，因为 CodeGraph 默认会自动监听文件变化。

7. 查看状态

codegraph status

查看当前项目索引状态。

8. 搜索符号

codegraph query UserService

用于搜索函数、类、方法等符号。

9. 探索代码流程

codegraph explore "How does a request reach the database?"

用于查询某个流程相关的代码、调用路径和影响范围。

10. 查看某个符号或文件

codegraph node UserService

可以查看某个符号的源码和调用信息。

11. 升级 CodeGraph

codegraph upgrade

升级到最新版本。

十四、使用示例

示例 1：分析请求链路

codegraph explore "How does a request reach the database?"

适合用来分析：

HTTP 请求 -> 路由 -> Controller -> Service -> 数据库

示例 2：查找某个服务类

codegraph query UserService

示例 3：查看某个服务类详情

codegraph node UserService

示例 4：查看项目索引状态

codegraph status

示例 5：查询 login 相关内容

codegraph query login
Search Results for"login":
functionloginApi (5988%)
api/login.js:4
  (data)
componentLoginPopup (5591%)
components/LoginPopup/LoginPopup.vue:1
filelogin.js (4980%)
api/login.js:1
fileLoginPopup.vue (4381%)
components/LoginPopup/LoginPopup.vue:21
import@/api/login.js (3371%)
components/LoginPopup/LoginPopup.vue:22
import {
wxLoginApi
        } from'@/api/login.js'
import@/api/login.js (2369%)
pages/login/index.vue:42
import {
loginApi,
wxLoginApi,
sendCodeApi
        } from'@/api/login.js'

十五、自动同步机制

CodeGraph 默认会监听项目文件变化。

当你修改、添加、删除代码文件后，它会自动更新本地索引。

一般情况下，不需要手动执行：

codegraph sync

只有以下情况可能需要手动同步：

文件监听被禁用
在脚本或 CI 环境中使用
索引状态异常
想在执行分析前强制同步一次

十六、Claude Code 中的使用方式

如果你使用 Claude Code，执行过：

codegraph install

并且项目中已经执行过：

codegraph init

那么 Claude Code 在需要理解代码结构时，就可以使用 CodeGraph MCP 工具。

项目根目录中存在：

.codegraph/

就表示该项目已经建立 CodeGraph 索引。

十七、手动配置 Claude Code

如果不使用自动安装，也可以手动配置 MCP。

示例配置：

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

如果想让 Claude Code 自动允许 CodeGraph 工具，可以添加权限：

{
"permissions": {
"allow": [
"mcp__codegraph__*"
    ]
  }
}

十八、卸载 CodeGraph

如果想移除 AI 工具里的 CodeGraph 配置，执行：

codegraph uninstall

如果想移除某个项目的索引，进入项目目录执行：

codegraph uninit

也可以手动删除项目中的：

.codegraph/

十九、注意事项

安装 CLI 后要重新打开终端。
codegraph install 只配置 AI 工具，不会索引项目。
每个项目都需要单独执行一次 codegraph init。
.codegraph/ 是本地索引目录。
项目没有 .codegraph/ 时，AI 不应该强行使用 CodeGraph。
自定义脚本或 CI 环境中，可以使用 codegraph sync 保证索引最新。
代码不会上传到外部服务。

二十、推荐使用步骤

如果你是第一次使用，可以按这个顺序：

# 1. 安装 CodeGraph
npm i -g @colbymchenry/codegraph
# 2. 配置 AI 工具
codegraph install
# 3. 进入项目
cd your-project
# 4. 初始化索引
codegraph init
# 5. 查看状态
codegraph status

之后就可以在 AI 工具里询问代码结构问题，例如：

这个登录接口的完整调用链是什么？

修改 UserService 会影响哪些地方？

这个项目的路由是如何连接到 controller 的？

二十一、总结

CodeGraph 的核心价值是：

让 AI 更快、更精准地理解代码结构。

它适合大型项目、复杂调用链分析、影响范围分析，以及需要本地化代码理解能力的团队或个人开发者。