CodeGraph 详解-把代码库变成可查询的知识图谱

当 AI 编程 Agent 进入一个陌生的代码库时,它真正耗费心力的环节往往不是"理解代码",而是"找到代码"。它需要先用 grep 搜关键字、用 glob 列文件、用 Read 逐个打开,反复试探才能拼凑出"谁调用了谁"“这个改动会影响哪些地方”。CodeGraph 做的事情,就是把这套反复试探的发现过程提前算好,存成一张代码的知识图谱,让 Agent 一次调用就能拿到精确答案。

CodeGraph 是一个本地优先(local-first)的代码智能工具。它用 tree-sitter 解析代码库,把每一个符号、每一条边、每一个文件都存进本地 SQLite 数据库,然后以可查询的知识图谱形式暴露出来——通过 Model Context Protocol (MCP)、命令行(CLI)以及 TypeScript 库三种方式供 Agent 和开发者使用 参考。

它的核心受众是 AI 编程 Agent:Claude Code、Cursor、Codex CLI、opencode、Hermes Agent、Gemini CLI、Antigravity IDE 和 Kiro。目标是让这些 Agent 在回答结构性问题(符号关系、调用图、代码组织)时,不必扫描文件,直接查询一个预先构建好的索引。

为什么需要它

Agent 探索代码库时,大部分预算都花在"发现"上——在能读代码之前先要找到正确的文件。CodeGraph 把这一步直接去掉:它把 Agent 恰好需要的代码在一次调用中递过去,于是符号关系、调用图、整体结构都不必再逐文件重建 参考。

可以把它理解成"代码的预建搜索索引",类似数据库为查询建的索引,而不是每次全表扫描。Agent 不再需要 grep + Read 反复出击几十次,而是问一个问题、拿到相关源码、符号之间的调用路径(包括 grep 跟不上的动态分派跳转)、以及改动的影响半径,通常一两次调用就回答完毕 参考。

官方在 7 个真实开源代码库上做过基准测试(每个分支取 4 次运行的中位数),给 Agent 接入 CodeGraph 后,不论仓库大小都获得了稳定收益 参考:

• 工具调用减少 58%
• 速度提升 22%
• 文件读取降到接近零

Token 和金钱的节省是真实存在的,但属于"随规模放大的额外奖励"——在体量不大、纠缠不深的仓库里收益较小且 noisy,只有当代码库和团队都变大时才会变得显著。

设计理念

CodeGraph 的两个底层选择决定了它和同类工具的差异。

100% 本地。没有任何数据离开你的机器。不需要 API key,不依赖任何外部服务,只有一个躺在 .codegraph/ 目录里的 SQLite 数据库 参考。这对企业代码、私有仓库而言是关键属性。

确定性抽取。所有符号和边都直接来自 AST(抽象语法树),绝不经过 LLM 总结。这意味着同一个代码库每次构建出的图谱是稳定、可复现的,不会因为模型抽风而漏掉某个函数或凭空造出一条不存在的调用关系 参考。

知识图谱里有什么

图谱里存三样东西:节点(nodes)、边(edges)、文件(files) 参考。

节点种类

节点表示符号和文件,取自一个固定的词汇表,保证跨语言查询的一致性:

file、module、class、struct、interface、trait、protocol、function、method、property、field、variable、constant、enum、enum_member、type_alias、namespace、parameter、import、export、route、component 参考。

注意其中 route 和 component 是面向 Web 框架和前端框架的特化节点——这正是它"框架感知"能力的体现。

边的种类

边表示节点之间的关系,同样来自固定词汇表:

contains、calls、imports、exports、extends、implements、references、type_of、returns、instantiates、overrides、decorates 参考。

来源与可信度(Provenance)

绝大多数边直接来自 AST。但静态解析天生处理不了动态分派(回调、观察者注册、React 重渲染、JSX 子组件等),这些地方如果不接上,调用流就会断。CodeGraph 用一组"合成器(synthesizer)"在动态分派边界上架桥,让调用流能从头连到尾 参考。

每一条合成出来的边都会被打上 provenance: 'heuristic' 标记,并附带生成它的连接点信息,在 explore 和 node 的结果里内联展示,让 Agent 清楚知道某条连接从何而来、可信度如何。

文件

文件节点除了结构信息,还带 FTS5 全文检索能力,所以按名字搜符号也很快 参考。

工作原理:四阶段流水线

CodeGraph 把源代码变成可查询图谱,经过四个阶段 参考:

源文件 → 抽取(tree-sitter)→ 数据库(节点/边/文件)
            ↓
      解析(导入、名称匹配、框架模式)
            ↓
      图查询(callers、callees、impact)
            ↓
      上下文构建(给 AI 用的 markdown / JSON)

1. 抽取(Extraction)

tree-sitter 把源代码解析成 AST。每种语言有专门的查询语句,从中抽出节点(函数、类、方法、类型等)和边(调用、导入、继承、实现等)。繁重的解析工作在主线程之外运行,避免阻塞 参考。

2. 存储(Storage)

所有结果进入本地 SQLite 数据库(.codegraph/codegraph.db),启用 FTS5 全文检索,使用打包运行时内置的 node:sqlite,以 WAL(Write-Ahead Logging)模式运行 参考。WAL 模式的好处是:并发读永远不会被写阻塞,这对 Agent 查询和后台索引同时进行至关重要。

3. 解析(Resolution)

抽取只产出节点和"原始边"。解析阶段把名字变成真正的连接 参考:

• 导入解析:把 import 指向真正的源文件,包括 tsconfig 的路径别名和 cargo workspace 成员。
• 调用解析:把函数调用解析到定义,依赖导入解析和名称匹配。
• 继承解析:在类型之间建立 extends / implements 关系。
• 框架路由:识别 Web 框架的路由文件,emit 出 route 节点,用 references 边连到对应的 handler 类或函数。
• 动态分派桥接:用合成器跨越回调注册、EventEmitter、React 重渲染(setState → render)、JSX 子组件(render → 子组件)、接口到实现的分派等边界。

4. 自动同步(Auto-sync)

MCP Server 用原生 OS 文件事件(FSEvents / inotify / ReadDirectoryChangesW)监听项目目录。变更被防抖处理、过滤到源码文件,然后增量同步——你写代码的同时图谱保持新鲜,无需任何配置 参考。

安装与快速上手

整个上手流程只有三步 参考。

第一步:安装 CLI

不需要预装 Node.js,一条命令即可抓取对应操作系统的构建:

# 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

如果你已经有 Node,npm i -g @colbymchenry/codegraph 在任何版本上都可用。CodeGraph 自带运行时——无需编译、无需原生构建,各平台表现一致。安装器把 codegraph 放到 PATH 上,但不会改动当前 shell,所以下一步之前要开一个新终端 参考。

第二步:接入你的 Agent

codegraph install

这条命令会自动检测并配置 Claude Code、Cursor、Codex CLI、opencode、Hermes Agent、Gemini CLI、Antigrigravity IDE 和 Kiro——把 CodeGraph 的 MCP Server 接进每一个 参考。这一步只连接 Agent,不索引任何代码。(npx @colbymchenry/codegraph 是一个快捷方式,下载并运行安装器一步到位。)

交互式安装器会做这些事 参考:

1. 询问要配置哪些 Agent(自动检测已安装的)。
2. 提示把 codegraph 安装到 PATH(让 Agent 能启动 MCP Server)。
3. 询问配置是应用到所有项目还是仅当前项目。
4. 为每个选中的 Agent 写入 MCP Server 配置和一个指令文件(如 CLAUDE.md、.cursor/rules/codegraph.mdc、~/.codex/AGENTS.md)。
5. 当目标是 Claude Code 时,设置自动允许权限。

如果需要非交互式(脚本 / CI)安装:

codegraph install --yes                              # 自动检测 agent,全局安装
codegraph install --target=cursor,claude --yes       # 显式指定目标
codegraph install --target=auto --location=local     # 检测到的 agent,项目本地
codegraph install --print-config codex               # 打印片段,不写文件

安装后重启 Agent,让 MCP Server 加载。

第三步:初始化每个项目

cd your-project
codegraph init

codegraph init 创建本地 .codegraph/ 目录,并在同一步里构建出完整图谱——一条命令搞定 参考。只要存在 .codegraph/ 目录,你的 Agent 就会自动使用 CodeGraph 工具。

卸载

改主意了?一条命令即可从它配置过的每个 Agent 里移除 CodeGraph:

codegraph uninstall

这会反向执行安装器——从每个已配置 Agent 中剥离 CodeGraph 的 MCP Server 配置、指令和权限。项目索引(.codegraph/)保持不动;要按项目移除用 codegraph uninit。--target 可指定从哪些 Agent 移除,--yes 可非交互运行 参考。

支持的平台

每个发布版本都自带一个自包含构建(打包 Node 运行时——无需编译),覆盖三大桌面操作系统,同时支持 x64 和 arm64 参考:

配置:几乎零配置

CodeGraph 是默认零配置的——不需要写任何东西或维护同步就能开始。语言支持按文件扩展名自动识别,无需按语言配置。唯一的可选文件 codegraph.json,只用于处理自定义扩展名、排除已跟踪目录、索引 gitignored 源码、索引嵌套 git 仓库这几种边缘情况 参考。

默认跳过什么

开箱即用,CodeGraph 会跳过三类内容 参考:

• 依赖、构建、缓存目录——node_modules、vendor、dist、build、target、.venv、Pods、.next 等所有支持技术栈里的同类目录。这样图谱里是你的代码,而不是第三方噪声。即便没有 .gitignore 也照样生效。
• .gitignore 里的任何东西——git 仓库里通过 git 来遵守,非 git 项目则直接读取 .gitignore(根目录和嵌套都读)。
• 大于 1 MB 的文件——生成的 bundle、压缩过的 JS、vendored 的大块文件。

排除或纳入更多

想多排除点东西,加到 .gitignore 即可。想把默认排除的目录重新纳入(比如你确实想索引某个 vendored 依赖),加一个取反规则——!vendor/ 参考。

默认规则统一适用,所以提交一个依赖或构建目录并不会强行把它塞进图谱——.gitignore 取反才是显式的 opt-in。

排除已跟踪的目录

.gitignore 只影响 git 尚未跟踪的文件——它没法把已经提交的目录剔除。比如一个已提交进仓库的 vendored 主题、SDK 或资源包(假设是 static/ 下的 Metonic 管理后台主题,几百个 .js 文件),没法用 .gitignore 排除。这种情况在 codegraph.json 里用 exclude 列出 参考:

{
  "exclude": ["static/", "**/vendor/**"]
}

每条是 gitignore 风格的模式,按项目根相对路径匹配,在 CodeGraph 看文件的所有地方(全量索引、增量 sync、文件监听)都生效。它对已跟踪文件也生效(这正是它的意义),且优先级高于一切。改完要重新 codegraph index。

索引 gitignored 的源码(第二种 VCS)

.gitignore 把文件挡在索引之外——通常这正是你想要的,但如果 gitignored 的文件其实是真正的第一方源码就不行了。这种场景是:项目同时被 SVN、Perforce 或其他 VCS 跟踪,有些源码提交到那个 VCS、并刻意列在 .gitignore 里以免落到 Git 中 参考。

把这些路径列在 codegraph.json 的 include 里强制纳入:

{
  "include": ["Tools/", "Local/typescript/"]
}

CodeGraph 直接从磁盘发现匹配文件——覆盖 .gitignore——在所有看文件的地方索引它们。几个要点:显式的 exclude 仍然优先(同一路径同时列在两边会被排除);node_modules、dist、.git 等内置跳过项永远不会被重新纳入。

自定义文件扩展名

如果项目用非标准扩展名(比如 .dota_lua 表示 Lua、.tpl 表示 PHP),这些文件默认会被跳过。在项目根的可选 codegraph.json 里映射 参考:

{
  "extensions": {
    ".dota_lua": "lua",
    ".tpl": "php"
  }
}

每个值是一个受支持语言的 id。映射会合并到内置默认值之上,冲突时以你的为准,所以也能重定向内置映射(如 ".h": "cpp")。把这个文件提交到仓库即可与团队共享。拼错的语言或有问题的文件会被警告并跳过——永远不会让索引崩溃。

索引嵌套的 git 仓库

CodeGraph 遵守 .gitignore,所以被 gitignore 的目录——包括其中嵌套的任何 git 仓库——都不会进图谱。如果你在 gitignored 目录里放了克隆的参考项目、vendored 副本或一堆无关仓库,CodeGraph 不会闯进去。

但如果你运行的是一个**“独立克隆的超级仓库”**——工作区自己的 .gitignore 把子仓库列出来以让 git status 安静,而你确实想把每个子仓库都索引进一张图——用 includeIgnored 把这些目录重新纳入 参考:

{
  "includeIgnored": ["packages/", "services/"]
}

CodeGraph 会下钻进你列的目录,按每个内嵌仓库自己的 git ls-files 索引,所以每个子仓库自己的 .gitignore 仍然被遵守。未追踪的嵌套仓库(没被 gitignore 的)会自动被索引——includeIgnored 只针对被 .gitignore 排除的那些。

数据放在哪

每个项目的数据放在项目根的 .codegraph/ 目录,里面是 SQLite 数据库 codegraph.db。一切都在本地,不出机器 参考。

索引与自动同步

初始化与索引

cd your-project
codegraph init      # 创建 .codegraph/ 并构建完整图谱——一步到位

codegraph init 创建本地 .codegraph/ 目录,并在同一步构建完整图谱,没有单独的索引步骤要在之后运行 参考。

全量 vs 增量

codegraph index           # 整个项目全量索引
codegraph index --force   # 从头重建
codegraph sync            # 增量——只更新改动的文件

sync 很快,因为它只重新解析变化的部分——文件监听器在每次编辑时自动跑的就是它 参考。

自动保持新鲜

在 Agent 会话期间你不需要手动跑 codegraph sync。 当 Agent 启动 codegraph serve --mcp 时,有三层机制协作让索引跟上代码,并在编辑到下一次同步之间的小窗口里绝不给 Agent 一个悄悄的错误答案 参考。

第一层:带防抖的文件监听器(常开)。 serve --mcp 启动原生文件监听器(macOS 用 FSEvents、Linux 用 inotify、Windows 用 ReadDirectoryChangesW)覆盖项目根。每次源文件的创建/修改/删除都被捕获,防抖定时器把编辑突发折叠成一次 sync。

agent 写 src/Widget.ts
  → 监听器触发(事件投递通常 <100ms)
  → 2000ms 防抖
  → sync 运行;Widget.ts 的节点和边进入索引
  → 下一次 agent 查询就能看到

防抖时间可通过 CODEGRAPH_WATCH_DEBOUNCE_MS 覆盖默认的 2000ms,范围被限制在 [100ms, 60s]。当构建步骤或格式化器在短时间内写大量文件时,把它调到 5000 或 10000 让监听器合并成一次 sync。

第二层:逐文件过期横幅——覆盖防抖窗口。 监听器防抖引入了一个小窗口(通常 2s),刚编辑的文件已在磁盘但还没进索引。CodeGraph 用逐文件过期横幅关闭这个窗口:如果任何 MCP 工具响应会引用一个正在等待重建索引的文件,响应前面会加一个 ⚠️ 横幅列出该过期文件 参考:

⚠️ Some files referenced below were edited since the last index sync —
their codegraph entries may be stale:
  - src/Widget.ts (edited 800ms ago, pending sync)
For accurate content of those specific files, Read them directly.
The rest of this response is fresh.

## Code Context
…

Agent 读完会直接对那个文件做一次 Read。所以即便在 2 秒防抖窗口里,Agent 也绝不会拿到一个悄悄的错误答案。未被响应引用的待处理文件则以小字脚注形式呈现。

第三层:连接时补齐——覆盖 MCP Server 没运行的间隙。 当编辑器/Agent(重新)连接到 MCP Server 时,codegraph 在回答第一个查询前会跑一次快速的基于文件系统的对账((size, mtime) 预过滤,再对剩余做内容哈希)。所以没有 MCP Server 运行时改动的文件——终端里 git pull、另一个编辑器的改动、退出的 Agent——都会在下一次会话的第一次工具调用时自动补齐。

何时手动 sync

几乎不需要。边缘场景是 参考:

• 监听器被禁用。 沙箱阻止本地文件监听器,或你设了 CODEGRAPH_NO_DAEMON=1 退出共享守护进程。这时 codegraph sync 是手动后备。
• CI 运行前预检。 如果你在 Agent 会话之外脚本化使用索引,脚本开头跑一次 codegraph sync 即可保证索引反映当前工作树。

检查状态

codegraph status

报告节点/边/文件数量、活动的 SQLite 后端和 journal 模式。在 Agent 会话里,MCP 侧的 codegraph_status 还会附带 ### Pending sync: 块 参考。

CLI 命令参考

完整命令清单 参考:

codegraph                         # 运行交互式安装器
codegraph install                 # 运行安装器(显式)
codegraph uninstall               # 从 agent 移除 CodeGraph(install 的逆操作)
codegraph init [path]             # 初始化项目 + 构建图谱(一步)
codegraph uninit [path]            # 从项目移除 CodeGraph(--force 跳过提示)
codegraph index [path]             # 全量重新索引(--force、--quiet、--verbose)
codegraph sync [path]              # 增量更新(--quiet)
codegraph status [path]            # 显示统计(--json)
codegraph unlock [path]            # 移除阻塞索引的过期锁文件
codegraph query <search>           # 按名字搜符号(--kind、--limit、--json)
codegraph explore <query>          # 相关符号源码 + 调用路径一次拿到(MCP codegraph_explore 同款输出)
codegraph node <symbol|file>       # 单个符号源码 + 调用者,或带行号读文件(codegraph_node 同款)
codegraph files [path]             # 显示文件结构(--format、--filter、--pattern、--max-depth、--json)
codegraph callers <symbol>         # 找出谁调用了某函数/方法(--limit、--json)
codegraph callees <symbol>         # 找出某函数/方法调用了什么(--limit、--json)
codegraph impact <symbol>          # 分析改动某符号会影响哪些代码(--depth、--json)
codegraph affected [files...]      # 找出受改动影响的测试文件
codegraph daemon                   # 管理后台守护进程——选一个停止(别名:daemons)
codegraph telemetry [on|off]       # 显示或更改匿名使用遥测
codegraph upgrade [version]        # 更新到最新版本(--check、--force)
codegraph version                  # 打印已安装版本(亦 -v、--version)
codegraph help [command]           # 显示帮助,可选针对单个命令

MCP Server(codegraph serve --mcp)由 Agent 自动启动,你不需要手动跑。

关于 init、index、sync:codegraph init 创建 .codegraph/ 目录并一步构建完整图谱(旧的 -i/--index 标志现在是 no-op,仅为不破坏既有脚本而保留)。之后文件监听器自动让图谱保持当前——index(全量重建)和 sync(增量更新)只有在监听器被禁用、或你在 Agent 会话外脚本化使用索引时才需要 参考。

查询命令 query、callers、callees、impact 都支持 --json 机器可读输出:

codegraph query UserService --kind class --limit 10
codegraph callers handleRequest --json
codegraph impact AuthMiddleware --depth 3

explore 和 node 是 codegraph_explore 与 codegraph_node MCP 工具的 CLI 面孔——输出一致——所以子 Agent 和非 MCP 工具链也能从 shell 触达图谱 参考。

你的第一个图谱

上手后的典型流程 参考:

# 索引
cd your-project
codegraph init          # 一步构建
codegraph index         # 全量重建(可选)
codegraph sync          # 增量更新(可选)

# 检查
codegraph status

# 查询
codegraph explore "how does login work"
codegraph query UserService          # 按名字找符号
codegraph callers handleRequest      # 谁调用了某函数
codegraph callees handleRequest      # 某函数调用了什么
codegraph impact AuthMiddleware      # 改动会影响什么

MCP Server 与 Agent 工具

CodeGraph 以 Model Context Protocol Server 形式运行。安装器配置过的 Agent 会自动启动它,你不需要手动启动 参考:

codegraph serve --mcp

当存在 .codegraph/ 索引时,Agent 拿到下面这些工具。在没有索引的工作区里,Server 宣布自己未激活且不列出任何工具——Agent 用内置工具正常工作,索引与否始终由你决定。

默认只有一个工具:codegraph_explore

默认情况下 Server 只暴露一个工具:codegraph_explore。它是 Read 等价的:给它一个自然语言问题或一袋符号和文件名,它返回相关符号的逐字、带行号的源码(按文件分组——和 Read 工具给你的形状一样),加上它们之间的调用路径(包括 grep 跟不上的动态分派跳转,如回调、React 重渲染、JSX 子组件),以及影响半径摘要 参考。一次调用通常就能回答整个问题。

只暴露一个强工具是刻意设计。实测的 Agent 行为表明:一个瞄准准确的工具,比一菜单更窄的工具更能引导 Agent 直达答案——选错的更少——而且 Agent 在回答问题和编辑代码时都会主动用它。

其他工具

还有七个工具,功能完整,但默认不列出——它们返回的一切已经在 codegraph_explore 响应里内联了 参考:

用 CODEGRAPH_MCP_TOOLS 环境变量可重新启用它们——一个逗号分隔的短名白名单,替换默认值:

CODEGRAPH_MCP_TOOLS=explore,node,search,callers

每个工具也有对应的 CLI 等价物。

Agent 该怎么用

CodeGraph 就是那个预建好的搜索索引。对于"X 是怎么工作的"、架构、流程(“X 如何到达 Y”)、X 在哪里这类问题——以及编辑代码时——Agent 应该用 codegraph_explore 回答并停下,通常零文件读取,而不是用 grep + Read 重新推导答案 参考。直接的 CodeGraph 答案是一到几次调用;一次 grep/read 探索是几十次。

MCP Server 会自动把这条指引在 MCP initialize 响应里递给主 Agent。因为子 Agent 和非 MCP 工具链看不到那个响应,安装器还会在每个 Agent 的指令文件里写一小段 marker 包裹的章节,指向 codegraph explore CLI 等价物。

Claude Code 的前置注入(可选)

从 v1.1.0 起,Claude Code 多了一个可选的前置注入钩子(front-load hook)。安装 codegraph install 时会问你是否启用(默认 yes;仅 Claude Code,因为它是唯一带 prompt 钩子的 Agent)。启用后,当你问一个结构性问题——“X 是怎么工作的”、“谁调用了 Y”、“追踪从 A 到 B 的流程”——CodeGraph 会把相关源码和调用路径预先注入到 prompt 里,让 Agent 直接从图谱作答,而不是靠 grep 重建 参考。

TypeScript API

CodeGraph 还提供一个 TypeScript API,公共接口是 CodeGraph 类 参考:

import CodeGraph from '@colbymchenry/codegraph';

const cg = await CodeGraph.init('/path/to/project');
// 或打开已有索引:
// const cg = await CodeGraph.open('/path/to/project');

await cg.indexAll({
  onProgress: (p) => console.log(`${p.phase}: ${p.current}/${p.total}`),
});

const results = cg.searchNodes('UserService');
const callers = cg.getCallers(results[0].node.id);
const context = await cg.buildContext('fix login bug', {
  maxNodes: 20,
  includeCode: true,
  format: 'markdown',
});
const impact = cg.getImpactRadius(results[0].node.id, 2);

cg.watch();   // 文件变更自动同步
cg.unwatch(); // 停止监听
cg.close();

核心方法

CommonJS 也支持——const { CodeGraph } = require('@colbymchenry/codegraph');。

底层构建块

同一入口还导出原语,供直接驱动图谱(而非通过 CodeGraph 门面)的调用方使用:DatabaseConnection、QueryBuilder、getDatabasePath、initGrammars / loadGrammarsForLanguages、FileLock 参考。

import {
  CodeGraph,
  DatabaseConnection,
  QueryBuilder,
  getDatabasePath,
  initGrammars,
  loadGrammarsForLanguages,
  FileLock,
} from '@colbymchenry/codegraph';

嵌入要求

• 通过 npm 安装(npm i @colbymchenry/codegraph),让匹配的 per-platform 包(携带编译好的库)被一并拉取。
• API 跑在你的运行时上,所以需要 Node 22.5+,因为有内置的 node:sqlite 模块(Electron 主进程在捆绑的 Node 为 22.5+ 时也合格)。CLI 和 MCP Server 不受影响——它们自带自包含的打包运行时,完全不需要 Node 参考。
• TypeScript 类型随包提供。保持 @types/node 可用,并设 skipLibCheck: true(常见默认值)。

集成的 Agent

交互式安装器自动检测并配置每个受支持的 Agent——把 CodeGraph MCP Server 接进每一个。对于使用指令文件的 Agent,它还会写一小段 marker 包裹的 CodeGraph 章节(CLAUDE.md、AGENTS.md 或 GEMINI.md),让子 Agent 和非 MCP 工具链学会 codegraph explore 命令;codegraph uninstall 会移除它 参考。

受支持的 Agent

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

手动设置

如果想自己接,全局安装后把 MCP Server 加到 ~/.claude.json 参考:

npm install -g @colbymchenry/codegraph

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

可选地在 ~/.claude/settings.json 自动允许 CodeGraph 工具:

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

一个通配符就自动批准所有 CodeGraph 工具。Server 默认只列一个工具——codegraph_explore——但如果你通过 CODEGRAPH_MCP_TOOLS 环境变量重新启用了别的,它们也已经被允许,不会再弹提示。

一个坑:Cursor 用错误的工作目录启动 MCP 子进程。安装器会通过注入一个 --path 参数替你处理;如果手动接 Cursor,要显式传项目路径 参考。

支持的语言

语言支持按文件扩展名自动识别,无需配置 参考:

合计覆盖 20+ 种语言,跨后端、前端、移动、游戏脚本、统计计算等场景。

框架路由识别

CodeGraph 会检测 Web 框架的路由文件,emit 出 route 节点,用 references 边连到对应的 handler 类或函数。于是查询某个视图或控制器的调用者,就能浮现出绑定它的 URL 模式 参考。

路由解析全自动——无需配置。框架文件被识别后,下一次 index 或 sync 就会在图谱里出现路由。

CI 里跑受影响的测试

codegraph affected 传递性地追踪导入依赖,找出一组改动的源文件会影响哪些测试文件——让 CI 只跑相关测试 参考:

codegraph affected src/utils.ts src/api.ts          # 文件作为参数
git diff --name-only | codegraph affected --stdin    # 从 git diff 管道传入
codegraph affected src/auth.ts --filter "e2e/*"      # 自定义测试文件模式

选项

CI / hook 示例

#!/usr/bin/env bash
AFFECTED=$(git diff --name-only HEAD | codegraph affected --stdin --quiet)
if [ -n "$AFFECTED" ]; then
  npx vitest run $AFFECTED
fi

故障排除

“CodeGraph not initialized”

在项目目录里先跑 codegraph init 参考。

索引慢

检查 node_modules 等大目录是否被排除(若 gitignored 则已经排除)。用 --quiet 减少输出开销。

MCP 撞上 database is locked

当前构建不应该出现:CodeGraph 自带 Node 运行时,用内置 node:sqlite 跑 WAL 模式,并发读永远不会被写阻塞。如果仍出现 参考:

• 装的是旧的(pre-0.9)版本。 重新安装以获得打包运行时。
• codegraph status 显示 Journal: 不是 wal——WAL 在这个文件系统上启不起来(常见于网络共享和 WSL2 的 /mnt),读可能被写阻塞。把项目(连同 .codegraph/)挪到本地磁盘。

MCP Server 连不上

Agent 自己启动 Server,你不用手动启动。确认项目已初始化并索引(codegraph status)、MCP 配置里的路径正确。若仍连不上,重跑 codegraph install 重写配置。

缺失符号

MCP Server 在保存时自动同步(等几秒)。需要的话手动跑 codegraph sync。检查文件语言是否受支持、是否在 .gitignore 或默认排除目录里。

Windows 和 WSL 共用一个 checkout

不要让两边指向同一个 .codegraph/:后台 Server 锁和 SQLite 索引绑定到写入它们的操作系统,而跨 WSL2/Windows 文件系统边界的 SQLite 锁不可靠。给每边各自一个索引——在一侧设 CODEGRAPH_DIR 为不同名字(比如 Windows 上 CODEGRAPH_DIR=.codegraph-win,WSL 仍用默认 .codegraph)。CodeGraph 索引和监听时会跳过任何兄弟 .codegraph-* 目录,所以两者不会互相绊倒 参考。

适用场景与小结

CodeGraph 适合的场景有一个共同点:Agent 需要回答"结构性问题"而非"读某段具体代码"。具体包括:

• 理解既有代码库——“登录是怎么工作的”"X 如何到达 Y"这类流程问题。
• 改动影响分析——改某个函数之前,先看它被谁调用、改完会影响哪些代码。
• 架构梳理——符号之间如何连接、调用图长什么样、路由如何绑定到 handler。
• CI 优化——只跑受改动影响的测试,而非全量。
• 大规模、纠缠深的代码库——团队和代码都变大后,token 和金钱节省会变得显著。

它的设计哲学是"少即是多":默认只暴露一个强工具 codegraph_explore,用确定性 AST 抽取而非 LLM 总结,把所有数据留在本地 SQLite。三层自动同步机制(文件监听器 + 过期横幅 + 连接时补齐)确保 Agent 写代码时图谱始终新鲜,且不会在防抖窗口里给出悄悄的错误答案。对追求 Agent 在私有代码库上高效、安全协作的团队,它是一个值得纳入工具链的本地优先选择。

官方文档入口在 colbymchenry.github.io/codegraph,项目源码托管在 github.com/colbymchenry/codegraph。