CodeGraph 深度研究：本地代码知识图谱与 AI Agent 加速器

摘要

CodeGraph（colbymchenry/codegraph）是一个本地优先的代码情报工具：用 tree-sitter 把 20+ 语种的整个代码库解析成 AST，再把符号、调用边、导入关系、框架路由等沉淀进本地 SQLite 知识图谱，并通过 MCP 暴露给 Claude Code、Cursor、Codex、Gemini 等 AI 编码代理。它的核心价值是用一次预索引替换 Agent 反复 grep/Read 的”瞎找”过程，实测可在大型仓库上节省约 16–35% 成本、47–57% Token、58–71% 工具调用次数，全程不出本机。

研究问题

• CodeGraph 解决的核心问题是什么？相比纯靠 Agent 文件扫描有何优势？
• 它的工作原理（解析、存储、查询、同步）是什么样的？
• 适用范围：支持哪些语言/框架/Agent？什么场景受益最大、什么场景不适用？
• 怎么使用：安装、初始化、CLI、MCP 工具集与库化集成？
• 与 Serena、repomix、tree-sitter-analyzer、向量化 RAG 等同类方案有什么差异？

发现

1. 定位：本地优先的”代码知识图谱 + MCP 服务器” — CodeGraph 自我定位为 “a local-first code-intelligence tool that turns any codebase into a queryable knowledge graph for AI coding agents”，所有数据落在 .codegraph/ 下的 SQLite，不出本机、不需要 API Key。来源

2. 解析与存储：tree-sitter + SQLite(FTS5) 的确定性抽取 — 用 tree-sitter 做增量 AST 解析，按语言查询提取节点（函数、类、方法、类型、路由、组件）和边（调用、导入、继承、引用、框架特定关系），结果写入启用 WAL 的 SQLite，并由 FTS5 提供全文检索。整个抽取过程”deterministic — derived from the AST, never LLM-summarized”，避免幻觉。来源

3. 核心能力：符号关系图、调用图、影响半径、框架路由识别 — 支持调用者/被调用者追溯、变更影响半径分析（impact radius）、跨语言桥接（Swift↔Objective-C、React Native bridge、Expo Modules、Fabric view）、以及覆盖 17 个 Web 框架的路由识别（Next.js / Nuxt / SvelteKit 等）。来源

4. 自动同步：原生文件事件 + 去抖动重建 — 使用 FSEvents（macOS）/ inotify（Linux）/ ReadDirectoryChangesW（Windows）做监听，默认 2 秒去抖动（CODEGRAPH_WATCH_DEBOUNCE_MS 可调 100ms–60s），并在 Agent 连接时做一次”reconciliation”补齐期间的漏更新。来源

5. 语言覆盖：20+ 主流语言全支持，框架感知扩展 — TypeScript、JavaScript、Python、Go、Rust、Java、C#、PHP、Ruby、C/C++、Objective-C、Swift、Kotlin、Scala、Dart、Lua、Luau、R、Svelte、Vue、Astro、Liquid、Pascal/Delphi 等。框架感知层进一步识别 SvelteKit 路由、Nuxt page/API/middleware、Scala 3 enums、Pascal/Delphi DFM/FMX 表单等。来源

6. 跨文件依赖解析覆盖率（官方实测） — Python / PHP / Svelte 100%，Go 96.6%，TypeScript 95.8%，Java 93.3%，Rust 86.7%，Liquid 73.8%。这是 CodeGraph 对外宣传的”图谱完整度”指标。来源

7. 基准：在 7 个真实仓库上的中位数收益 — 相比 Agent 不接 CodeGraph：成本 ↓16%、Token ↓47%、响应时间 ↓22%、工具调用 ↓58%。在大仓极端样例上：VS Code 仓 1.79M → 545k Token（-70%）、TypeScript 项目 32 次 → 3 次工具调用。来源 对照来源

8. 安装与初始化：一行脚本 + 自动接入 Agent — 提供独立 Bundled Node 安装脚本（curl ... install.sh | sh / irm ... install.ps1 | iex）以及 npm 全局包 @colbymchenry/codegraph；codegraph install 会自动检测并写入 Claude Code、Cursor、Codex CLI、opencode、Hermes、Gemini CLI、Antigravity IDE、Kiro 的 MCP 配置；进入项目后 codegraph init 建索引。来源

9. CLI 查询接口 — 常用命令：codegraph explore "How does authentication work?"（架构问答）、codegraph search UserService（按名查符号）、codegraph callers handleLogin（找全部调用点）、codegraph impact changePassword --depth=2（影响半径）、codegraph affected src/auth.ts（找被该文件影响的测试）。来源

10. MCP 工具集（暴露给 Agent 的四个核心工具） —

    • codegraph_explore：一次调用回答架构性问题（”鉴权怎么走的”），等价于在图谱上做有方向的多跳查询；
    • codegraph_node：读单个符号的源码 + 上下游依赖；
    • codegraph_search：按名定位符号；
    • codegraph_callers：列所有调用点。
      通过 CODEGRAPH_MCP_TOOLS 可启用更多扩展工具（codegraph_callees / codegraph_impact / codegraph_affected / codegraph_files / codegraph_status）。详细参数与样例见下文「四个核心 MCP 工具详解」。来源

11. 库化嵌入：可作为 Node 库直接调用 —

    import CodeGraph from '@colbymchenry/codegraph';
    const cg = await CodeGraph.init('/path/to/project');
    await cg.indexAll();
    const results = cg.searchNodes('UserService');
    cg.watch();

    适合做自定义脚手架/CI 影响分析/自家 Agent 的上下文供给。来源

12. 零配置 + 可控环境变量 — 无需配置文件，自动排除 node_modules / vendor / dist / build / target / .venv / Pods / .next 与 .gitignore 中的目录、>1MB 文件；可用 .gitignore 反向规则（!vendor/）覆盖。环境变量包括 CODEGRAPH_WATCH_DEBOUNCE_MS、CODEGRAPH_NO_DAEMON、CODEGRAPH_DIR、CODEGRAPH_MCP_TOOLS、CODEGRAPH_TELEMETRY。来源

13. 隐私与遥测 — 索引完全本地；遥测仅上报命令使用频次、语言索引频次等聚合数据，不含代码/路径/IP；codegraph telemetry off 或 CODEGRAPH_TELEMETRY=0 关闭。许可证 MIT。来源

14. 与同类方案对比 —

    • vs 纯 Agent（Claude Code 默认行为）：CodeGraph 把”反复 grep + 文件读”折叠成一次 SQL 级查询，大仓收益最大；
    • vs Tree-sitter Analyzer（另一个 MCP 工具）：在符号密集仓如 Django 上 CodeGraph 优势更明显（-35% Token），TSA 在中位数成本上略低（-11% vs -4%）；
    • vs 向量 RAG（embedding 检索）：CodeGraph 强在结构化/精确匹配查询（”谁调用了 X”、”改动 Y 影响哪些测试”），向量库更适合”找做某件事的代码”这类语义相似查询，两者互补而非替代；
    • vs Serena / repomix：Serena 偏 LSP 驱动的语义工具集、repomix 偏”打包整仓喂大模型”，CodeGraph 主打”持续运行的本地图谱 + MCP 直查”，调用粒度更细、不依赖一次性塞 Token。来源 基准对照

对比与判断

• 最适合的场景：中大型多语言单体仓 / monorepo、需要让 AI Agent 跨文件追依赖、做重构影响分析、做”哪里调用了它”类问题。在 VS Code、Swift Compiler、FastAPI 这类规模上，Token 与工具调用降幅最大。
• 不太适合的场景：
  • <100 文件的小仓，预索引 + MCP 调用的固定开销吃掉收益（Gin 仓只有 -15% 成本）；
  • “找做某件事的代码”这类纯语义检索问题，向量 RAG 仍优；
  • 高度动态/反射/字符串拼接调用为主的代码（图谱无法静态解出全部边）。
• 工程取舍：
  • 用确定性 AST 抽取换可解释性和稳定性，代价是没法像 LLM 那样总结意图；
  • 用本地 SQLite 换隐私和零成本调用，代价是不像云端服务那样自动随团队共享索引（其官方有 hosted 版 waitlist）；
  • 自动监听 + 去抖动让”代码改完图谱就过时”的痛点最小化，但大改动落盘瞬间仍会触发短暂的重建窗口。
• 判断：对接入 Claude Code / Cursor 等 Agent 且仓库规模 ≥ 几千文件、跨语言或多框架的团队，CodeGraph 属于”装上几乎不亏”的工具——成本和延迟都在降，且可观测、可关闭、不出本机。对小项目或主要靠语义搜索的研究型代码库，先评估再决定。

四个核心 MCP 工具详解

CodeGraph 暴露给 AI 的”四件套”是 codegraph_explore / codegraph_node / codegraph_search / codegraph_callers；通过 CODEGRAPH_MCP_TOOLS 环境变量还能解锁 codegraph_callees / codegraph_impact / codegraph_affected / codegraph_files / codegraph_status 等扩展工具。每个 MCP 工具都有同名 CLI 命令（codegraph explore "..." ），不经 LLM 也能直接跑。

下面分工具详解。所有样例都在 shield 仓里实跑，输出已截断为关键片段。

1. codegraph_explore —— 架构问答的”瑞士军刀”

做什么：给一段自然语言描述，返回相关符号的源码 + 调用路径 + 影响半径，相当于把”模糊查询 → 多跳遍历图谱 → 回填源码”折叠成一次调用。这是日常用得最多的一个工具，本次实测 v2 中 14 次 codegraph 调用里有 10 次是它。

主要参数：

• query（必填）：自然语言或符号名，支持多个词。
• max_files（可选）：限制返回源码的文件数，避免单次结果过大。

典型用途：

• “鉴权流程怎么走的？”
• “AI 参数从前端怎么传到后端？”
• “整个购买流程涉及哪些组件？”

实跑样例（codegraph explore "AI 参数传递路径" --max-files 1）：

## Exploration: AI 参数传递路径
Found 143 symbols across 61 files.

### Blast radius — what depends on these (update/verify before editing)
- AIMessage (packages/copilot/core/src/chat-engine/type.ts:140) — 24 callers in
  packages/app-pc/pages/debug/markdown-debug.vue, ... +11 more;
  tests: packages/copilot/core/src/chat-engine/store/__tests__/message-store.test.ts
- AiPPTItem (packages/shared-composables/src/service/use-ai-ppt.ts:13) — 10 callers ...

### Relationships
**references:**  AIMessage → AIMessageContent ; PPTContextParams → AiPPTItem ; ...
**calls:**       useGetAiNews → useQuery ; useGetAiNewsWithQuestions → useGetAiNews

一次调用 = 定位 + 影响半径 + 引用关系 + 调用关系。这就是为什么 Q1 / Q4 在实战中只用 2 次 explore 就完成 baseline 11–13 turns 的工作。

2. codegraph_node —— 看一个符号的”完整档案”

做什么：拿单个符号的精确源码（含行号）+ 它的 caller / callee 列表。也支持”文件模式”——传文件路径就读整文件 + 列出文件内符号 + 谁依赖这个文件。

主要参数：

• name（必填）：符号名或文件路径。
• file（可选）：在符号同名重复时用文件路径消歧。
• offset / limit（可选，文件模式）：1-based 行号区间分页读取。
• symbols_only（可选，文件模式）：只列符号映射 + 依赖，不返回源码。

典型用途：

• “看下 useAiStore 这个 store 的源码 + 谁在用”
• “这个组件 UserCard.vue 怎么实现的？”
• “把 getOperation 函数贴出来 + 列出调用者”

实跑样例（codegraph node getOperation）：

## getOperation (function)
**Location:** packages/shared-utils/src/middleware.ts:95
**Signature:** (status: number, token = '', cookieCode = '', urlCode = '', loginPlatform = '')

@param cookieCode
@param urlCode 新域名：company_from 旧域名：三级域名或者company_from
@returns

```typescript
95  export const getOperation = (status: number, token = '', cookieCode = '', ...) => {
96    if (token && loginPlatform === LOGIN_PLATFORM.INDIVIDUAL && !cookieCode) {
97      return OPERATION.SWITCH;
98    }
99    if (status === 401 || !token) {
100     return urlCode ? OPERATION.REDIRECT : OPERATION.LOGIN;
101   }
...

返回带行号的精确源码，比 `Read` 整文件更省 token（只返回相关函数体）。

### 3. `codegraph_search` —— 关键词模糊定位

**做什么**：基于 SQLite 的 FTS5 全文索引按符号名模糊匹配，返回 top-N 命中（按相关度排序，带匹配分）。比 `grep -r` 在大仓上**快几个数量级**——索引里只搜符号字段，不用扫整仓文本。

**主要参数**：
- `search`（必填）：搜索词。
- `limit`（可选，默认 10）：返回条数。
- `kind`（可选）：按节点类型过滤，如 `function` / `class` / `interface` / `component` / `route`。

**典型用途**：
- "项目里有没有叫 `Purchase` 的东西？"
- "找一下所有名字带 `useAi` 的 composable"
- "有没有定义 `LoginRequest` 这个类型？"

**实跑样例**（`codegraph query getOperation -l 3`）：

Search Results for “getOperation”:

function getOperation (10821%)
packages/shared-utils/src/middleware.ts:95
(status: number, token = ‘’, cookieCode = ‘’, urlCode = ‘’, loginPlatform = ‘’)

method getOperationsCount (5836%)
packages/copilot/core/src/chat-engine/event-stream/activity-manager.ts:190
(content: Record<string, any> | null | undefined): number

import @lexiang/shield-utils (1068%)
packages/app-admin/server/middleware/auth.ts:2

`(10821%)` 是 FTS5 的相关度分数，越高越精确。**注意：CLI 命令名是 `codegraph query`，但 MCP 工具名是 `codegraph_search`**——这是历史遗留命名，记一下。

### 4. `codegraph_callers` —— 反向查"谁调用了我"

**做什么**：给一个符号，返回所有调用它的函数/方法。直接走图谱的反向边，不用 grep 聚合，准确率取决于跨文件解析覆盖率（TS 95.8% / Python 100% / Rust 86.7%）。

**主要参数**：
- `symbol`（必填）：被调用的符号名。
- `limit`（可选，默认 20）：最多返回几个调用点。
- `json`（可选）：以 JSON 输出，便于脚本聚合。

**典型用途**：
- "改 `usePurchaseFlow` 之前，先看看谁在用"
- "如果删掉 `oldHelper()`，会牵连哪些地方？"
- "这个事件总线 `emit('foo')` 在哪里被监听？"

**实跑样例**（`codegraph callers getOperation -l 5`）：

Callers of “getOperation” (3):
file auth.ts packages/app-admin/server/middleware/auth.ts:1
file auth.ts packages/app-h5/server/middleware/auth.ts:1
file auth.ts packages/app-pc/server/middleware/auth.ts:1

三个子包的鉴权中间件都依赖这个函数——这就是为什么 Q4 鉴权流程问题在 v2 实测中 after 端只用 2 次 `codegraph_explore` 就拿到完整链路（explore 内部已经把 callers 信息聚合进去）。

### 扩展工具（通过 `CODEGRAPH_MCP_TOOLS` 启用）

| 工具 | 做什么 | 关键参数 | 何时用 |
|---|---|---|---|
| `codegraph_callees` | 一个符号**调用了**谁 | `symbol`, `limit`, `json` | 想读懂某函数依赖的下游接口 |
| `codegraph_impact` | 改一个符号会影响哪些代码（深度可调） | `symbol`, `depth`（默认 2）, `json` | 重构前评估爆炸半径 |
| `codegraph_affected` | 改了 X 文件会牵连哪些**测试** | `files...`, `depth`, `filter`（glob 过滤测试） | CI 流水线 / pre-commit 跑增量测试 |
| `codegraph_files` | 列项目文件结构（带语言/符号数元数据） | `filter`, `pattern`, `format=tree\|flat\|grouped` | 给 AI 当目录概览 |
| `codegraph_status` | 索引健康检查 | `path`, `json` | 调试 / 排查"AI 没用上 codegraph" |

例如 `codegraph impact getOperation -d 1` 输出：

Impact of changing “getOperation” — 4 affected symbols:
packages/shared-utils/src/middleware.ts function getOperation:95
packages/app-admin/server/middleware/auth.ts file auth.ts:1
packages/app-h5/server/middleware/auth.ts file auth.ts:1
packages/app-pc/server/middleware/auth.ts file auth.ts:1

`codegraph affected` 配合 git diff 是 CI 的核武器：

```bash
codegraph affected $(git diff --name-only origin/main...HEAD) -f "**/*.spec.ts"
# → 只跑被本次改动影响的测试文件

工具速查表

你想做的事	用哪个	一句口诀
搞清楚一段功能/流程怎么走	codegraph_explore	“我不知道在哪、给我一把抓”
看具体一个符号长啥样	codegraph_node	“我知道名字、给我源码 + 上下游”
找名字像 X 的东西	codegraph_search	“比 grep 快十倍的符号搜索”
改它前先看看谁依赖	codegraph_callers / codegraph_impact	“评估爆炸半径”
改了文件 X 跑哪些测试	codegraph_affected	“增量测试选择器”
它内部又调了谁	codegraph_callees	“看下游接口”
列目录结构	codegraph_files	“比 tree 多带元数据”
排查索引状态	codegraph_status	“调试入口”

如何优雅地使用 CodeGraph

把 CodeGraph 当成”给 Agent 配的本地代码图谱数据库”来用，而不是”装上就行的银弹”。下面是一套从选型到日常维护的可执行手册，部分要点来自《CodeGraph 实战：在 shield monorepo 上做 A/B 基准测试》中验证过的结论。

1. 先做选型自检（5 分钟）

只在符合下面”高 ROI”特征时才装：

• 仓库规模 ≥ ~500 文件，或属于 monorepo / 多子包；
• 仓库语言在它的 20+ 支持表内（TS/JS/Vue/Python/Go/Rust/Java/Swift/PHP 等）；
• 你常问 Agent 跨文件类问题——“谁调用了 X”、”改 Y 影响哪些测试”、”鉴权链路怎么走”；
• 仓库内的代码不是高度动态/反射/字符串拼接调用为主（图谱解不出动态边）。

反过来不要装的情形：单文件脚本、< 100 文件的研究项目、纯靠”找做某件事的代码”这种语义相似检索的场景（继续用向量 RAG 即可）。

2. 安装：永远走 npm，不走管道脚本

# 推荐：受 Node 生态管控、可锁版本
npm i -g @colbymchenry/codegraph

# 不推荐：curl ... | sh 管道脚本，调试与回滚都麻烦

装完先确认版本：codegraph --version。

3. 初始化：先 init，再 install

正确顺序是 先在仓库里建索引，再注册到 Agent，避免 Agent 接到空索引误判项目。

cd /path/to/your-repo
codegraph init                    # 建 .codegraph/ 索引（不消耗 LLM token）
codegraph status                  # 看节点/边数、文件总量是否符合预期

codegraph install \
  --target claude \               # 只装 Claude Code，避免污染其它 Agent
  --location global \             # 写到 ~/.claude.json，全局可用
  -y                              # 跳过交互

-y 无人值守模式默认 --location=global --target=auto，会一次性给所有检测到的 Agent 都注册——团队多 Agent 环境下慎用，建议用 --target claude 之类显式指定。

4. 让 Agent 真的”愿意”调用 CodeGraph

实战中遇到的最大坑是 Agent 即使有 codegraph MCP 也可能选 grep+Read 路径，这时你白付索引成本。三件事让模型主动用：

1. codegraph install 已经在 ~/.claude/CLAUDE.md 里追加了一段 CODEGRAPH_START/END 区块，明确告诉模型 “在 .codegraph/ 存在的仓库里，先用 codegraph_explore/codegraph_node 再考虑 grep”。别删它。
2. 在仓库的项目级 CLAUDE.md 里再叠一句：”工作目录就是仓库根目录，需要查代码请直接调 codegraph_explore，不要反问’是哪个仓库’”——可以避免 LLM 偶发的”反问而非干活”退化（实战中出现过 2 次）。
3. 写需求 prompt 时，在第一句给出明确的方向词（”鉴权”、”购买流程”），CodeGraph 的 FTS5 是关键词匹配，越具体命中越准。

5. 用对工具，别让模型乱跑

四个 MCP 工具的判断顺序：

你想做的事	优先用	理由
一次理清架构 / 调用链 / 业务流程	codegraph_explore	一次查询返回相关符号源码 + 调用路径，相当于多跳查询折叠
已知符号名，要看源码和调用者	codegraph_node	单符号 + 上下游一次拿全
只知道关键词，要先定位	codegraph_search	FTS5 模糊匹配，比 grep -r 快几个数量级
“谁调用了我”类影响分析	codegraph_callers / codegraph_impact	直接走图谱边，不用 grep 聚合

CLI 端命令同名（codegraph explore "..." 等），写脚本或 CI 报告时直接调，不必经 LLM。

5.5 日常提问：自然语言就够，不用刻意点名 CodeGraph

只要第 4 节的”让 Agent 愿意调用”配置都到位，日常提问继续用自然语言即可，不需要在 prompt 里写”用 codegraph 帮我……”。模型会按你的问法自动选工具。基于实战 v2 的工具用量证据，把日常代码问题分成 3 类：

类型	共同特征	模型自动会选	是否要点名 codegraph
A. 位置已明型	prompt 里出现具体目录或文件路径（pages/、config.ts）	Glob / Read	❌ 绝对不要点名，会让 codegraph 用在它不该用的场景
B. 跨包依赖型	只有功能/概念描述，不知道在哪	codegraph_explore / codegraph_callers / codegraph_impact	不需要，自然语言就触发
C. 已知符号型	知道符号名（函数 / 类 / 组件）	codegraph_node 或 Grep+Read	可选；想极致省 token 才显式点名

示例对照：

B 类（跨包依赖，自然语言）：
  ✅ "AI 参数是怎么从前端传到后端的？画个调用链"
  ✅ "登录后的请求拦截器在哪里挂的？"
  ✅ "改 usePurchaseFlow 会影响哪些 admin 页面？"
  → 模型会自动调 codegraph_explore / codegraph_callers / codegraph_impact

A 类（位置已明，自然语言）：
  ✅ "看一下 packages/app-pc/middleware/ 都做了什么"
  ❌ 不要写："用 codegraph 看一下 packages/app-pc/middleware/"
  → prompt 里有路径，模型自己会走 Glob/Read。强行加 "用 codegraph"
    反而让它绕路（实测 +186% 成本）

C 类（已知符号，自然语言够；想极致优化时点名）：
  ✅ "看下 useAiStore 这个 store 的源码 + 谁在用"  → 通常自动选对
  ⚡ "用 codegraph_node 看 useAiStore"           → 一定走图谱，最省 token
  ⚡ 或直接命令行：codegraph node useAiStore     → 不经 LLM，零 token

只有两种情况建议显式点名 codegraph：

1. 纠偏：观察到模型已经反复 Bash grep -r 还没收敛，丢一句”用 codegraph_explore 查一下”；
2. 极致省 token：你已经知道符号名，懒得让模型再绕一步搜索定位。

口诀：自然语言提问，把 “用 codegraph” 当成调试工具，而不是日常习惯。 显式点名只在 C 类的极致省钱场景或纠偏场景才有意义；在 A 类里反而是反模式。

6. 索引维护：默认自动，重大改动后手动校准

• 正常开发：FSEvents/inotify 监听 + 2 秒去抖动，存盘后秒级更新，啥也不用做；
• 拉新分支 / merge 大量改动：跑一次 codegraph sync 显式同步，避免老索引误导 Agent；
• 依赖大改 / 删除子包 / 改造目录结构：codegraph init --force 重建（或 uninit 后再 init）；
• 节点数突然爆涨/爆跌：codegraph status 看下，多半是 .gitignore 改了导致包含/排除变化；
• CI 场景：在 PR 流水线里 codegraph init && codegraph affected $(git diff --name-only) 能直接列出改动影响的测试，省去自己写依赖图。

7. .codegraph/ 的版本库策略

强烈建议 .codegraph/ 加入 .gitignore，不要入仓。三个理由：

1. SQLite 是二进制，git diff 没意义；
2. 索引规模在中型仓上是几十到几百 MB（shield 仓 95 MB），污染仓库历史；
3. 不同同事的 OS / Node 版本可能让索引格式差一截，入仓反而引发”我这边索引为啥不一样”的争论。

正确做法：每位同事各自 codegraph init 一次，后续监听自动维护。等官方 hosted 版上线后，再考虑团队层共享索引。

8. 控制成本与隐私的开关

• 关遥测：codegraph telemetry off 或 CODEGRAPH_TELEMETRY=0（即使官方说只上报聚合指标，敏感企业仓库直接关掉更省心）；
• 关后台 daemon：CODEGRAPH_NO_DAEMON=1，省一个常驻进程，代价是不再自动同步；
• 调监听去抖动：CODEGRAPH_WATCH_DEBOUNCE_MS=5000（默认 2000ms），改频繁的项目调大可减少 CPU 抖动；
• 自定义索引目录：CODEGRAPH_DIR=.cache/codegraph，把索引挪到缓存目录便于统一清理；
• 启用扩展 MCP 工具：CODEGRAPH_MCP_TOOLS=callees,impact,files,status 等（官方未公开完整列表，跑 codegraph --help 确认）。

9. 调试：MCP 不工作的排查顺序

实战中最容易卡住的就是”装了但 Agent 没用上”。按这个顺序查：

1. codegraph status 在仓库根目录能跑、有数据 → 索引 OK；
2. claude mcp list 能看到 codegraph: ✓ Connected → MCP 注册 OK；
3. 让 Agent 跑一次 “用 codegraph_search 找 X”，如果它说”没有这个工具” → MCP 没加载，多半是 Agent 进程没重启，或者 CLAUDE_CONFIG_DIR 指向了别的配置目录（公司内部代理常见问题）；
4. 如果它有工具但不调，回到第 4 节优化提示词。

10. 卸载与回退（保持仓库干净）

codegraph uninstall                 # 从所有 Agent 配置中移除 MCP 注册
cd /path/to/repo && codegraph uninit # 删 .codegraph/ 目录
npm un -g @colbymchenry/codegraph    # 卸载二进制（可选）

这三步能 100% 还原。~/.claude/CLAUDE.md 中的 CODEGRAPH_START/END 区块也会被 uninstall 一并清理，不会留垃圾。

不确定性

• README 标注的 49k stars / 3k forks 与早先文档显示的 43k stars 不一致，星数处于快速增长阶段，绝对值需以最新仓库页为准。
• “16% 成本 / 47% Token / 22% 时延 / 58% 工具调用”是官方在 7 个仓库上的中位数；其他第三方文章给出的 35% / 57% / 46% / 71% 是更早一版的数据，具体收益高度依赖仓库规模、Agent 行为和提示词。
• 跨文件解析覆盖率指的是”被解析出的边占静态可达边的比例”，对动态语言（Ruby/Python 反射、JS eval、依赖注入框架）的真实召回率仍可能低于 100%。
• MCP 工具列表中除四个核心工具外，CODEGRAPH_MCP_TOOLS 启用的扩展工具未在公开文档中详细列出，需要读源码或运行 codegraph --help 确认。

后续行动

• 在本地一个中型 TypeScript / Python 单体仓上跑 codegraph init + codegraph install，对比 Claude Code 接入前后同一组架构问题的 Token 与工具调用次数。
• 阅读 .codegraph/ 下的 SQLite schema，确认节点/边表结构与 FTS5 索引字段，评估能否直接 SQL 查询做自定义分析。
• 试一次 codegraph impact <symbol> --depth=2 与 codegraph affected <file>，验证它在本仓库重构场景的有效性。
• 跟踪 hosted 版（getcodegraph.com waitlist）发布动态，看是否要在团队层共享图谱。

来源

• GitHub: colbymchenry/codegraph
• CodeGraph 官方站点
• Getting Started: Introduction
• Reference: Languages
• 阿里云开发者社区：CodeGraph 深度解析
• 掘金：CodeGraph 让 Claude Code Token 消耗降 57%
• 掘金：CodeGraph 节省 94% 探索调用
• arXiv: Reliable Graph-RAG for Codebases (AST-Derived vs LLM-Extracted)