CodeGraph 使用指南

快速安装

一键安装（推荐，无需 Node.js）

bash

# 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）

bash

npm i -g @colbymchenry/codegraph

升级

bash

codegraph upgrade # 升级到最新版
codegraph upgrade --check # 检查是否有新版本
codegraph upgrade <版本号> # 锁定特定版本

关联 AI 代理

安装 CLI 后，运行以下命令将 CodeGraph 连接到你的 AI 编码代理：

bash

codegraph install

这会自动检测你已安装的 AI 代理（Claude Code、Cursor、Codex CLI、OpenCode、Hermes Agent、Gemini CLI 等），并为每个代理配置 MCP 服务器。你只需选择要启用的代理即可。

支持的非交互式安装：

bash

codegraph install --yes # 自动检测并安装
codegraph install --target=claude,opencode --yes # 指定目标代理
codegraph install --print-config claude # 仅打印配置片段，不写入文件

可选参数：

参数

可选值

说明

--targetauto

,all,none, 或 csv

指定要配置的代理

--locationglobal

,local

全局生效或仅当前项目

--yes

(布尔值)

非交互模式

--print-config

代理 ID

仅打印配置片段

初始化项目

进入你的项目目录，运行：

bash

cd your-project
codegraph init

这会在项目根目录创建.codegraph/目录并构建完整的知识图谱。构建完成后会自动监听文件变化并增量更新索引。

各代理中的使用方式

Claude Code

codegraph install会自动配置 Claude Code 的 MCP 服务器。安装后重启 Claude Code 即可。Claude Code 会自动使用codegraph_exploreMCP 工具来查询代码结构。

如需手动配置，编辑~/.claude.json：

json

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

可选：在~/.claude/settings.json中启用自动授权：

json

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

OpenCode

codegraph install同样支持自动检测 OpenCode。安装后重启 OpenCode 即可。

OpenCode 的 MCP 配置会被写入对应的 MCP 配置文件中，CodeGraph 会自动创建~/.config/opencode/mcp.json或类似路径的配置。

Codex CLI

Codex CLI 同样被codegraph install自动支持。配置完成后重启 Codex CLI，CodeGraph 的 MCP 工具即可在 Codex 中使用。

Hermes Agent

同样支持自动配置。安装后重启 Hermes Agent 即可使用。

ZCode

CodeGraph 未被codegraph install自动检测列表收录，需手动添加 MCP 服务器配置。

方式一：通过 ZCode 设置面板添加

  1. 打开 ZCode，进入设置 → MCP 服务器

  2. 点击右上角新建 MCP 服务器，类型选择stdio（本地命令）

  3. 填写以下信息：

字段

值

名称

codegraph

命令

codegraph

参数

serve --mcp

  1. 选择作用域（用户作用域让所有项目可用，工作区仅当前项目）

  2. 点击添加并确认开关处于启用状态

方式二：手动编辑配置文件

ZCode 读取以下配置路径：

  • 用户级：~/.zcode/cli/config.json，键mcp.servers

  • 项目级：<项目根>/.zcode/config.json，键mcp.servers

在mcp.servers中添加：

json

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

方式三：通过导入功能（如果你已在其他代理中配置过）

ZCode 支持从 Claude Code、Codex CLI、OpenCode 等外部 Agent 一键导入 MCP 配置。在MCP 服务器页面点击右上角导入图标，勾选 CodeGraph 即可。

配置完成后重启 ZCode，即可在项目中看到 CodeGraph 的codegraph_explore工具自动可用。

CLI 常用命令

命令

说明

codegraph status

查看当前索引统计

codegraph explore <查询>

核心功能 — 一次查询返回相关源码 + 调用链 + 影响范围

codegraph node <符号/文件>

查看单个符号的源码或读取文件（带行号）

codegraph callers <符号>

查找谁调用了某个函数

codegraph callees <符号>

查找某个函数调用了什么

codegraph impact <符号>

分析修改某符号的影响范围

codegraph affected <文件...>

找出受更改影响的测试文件

codegraph query <搜索>

搜索符号

codegraph files

查看文件结构

codegraph index [路径]

手动全量索引

codegraph sync [路径]

增量更新索引

codegraph uninstall

从所有代理中移除 CodeGraph 配置（加--keep-cli保留 CLI）

codegraph uninit [路径]

移除项目的索引

affected 命令的典型用法：

bash

# 找出 git 变动的受影响测试文件
git diff --name-only HEAD | codegraph affected --stdin --quiet

# 然后在 CI 中只运行受影响测试
npx vitest run $(git diff --name-only HEAD | codegraph affected --stdin --quiet)

卸载

bash

codegraph uninstall # 移除所有代理配置 + CLI 自身
codegraph uninstall --keep-cli # 仅移除代理配置，保留 CLI
codegraph uninit # 移除当前项目的索引

关键点

  • CodeGraph仅索引你自己的代码，自动跳过node_modules、dist、.gitignore中的目录

  • 图谱构建后自动监听文件变化，无需手动重新索引

  • 支持多项目同时索引— 通过projectPath参数可在 MCP 会话中切换项目

  • 零配置即可使用，不支持的文件扩展名可通过项目根codegraph.json映射

  • 所有数据100% 本地，不发送你的代码