# codegraph

**Repository Path**: longdaozhang/codegraph

## Basic Information

- **Project Name**: codegraph
- **Description**: https://github.com/colbymchenry/codegraph
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-06-01
- **Last Updated**: 2026-06-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">

# CodeGraph

### 为 Claude Code、Cursor、Codex、OpenCode、Hermes Agent、Gemini、Antigravity 和 Kiro 赋能语义代码智能

**~16% 更便宜 · ~58% 更少工具调用 · 100% 本地化**

### [文档与网站 →](https://colbymchenry.github.io/codegraph/)

[![npm version](https://img.shields.io/npm/v/@colbymchenry/codegraph.svg)](https://www.npmjs.com/package/@colbymchenry/codegraph)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Self-contained](https://img.shields.io/badge/Node.js-bundled%20%C2%B7%20none%20required-brightgreen.svg)](https://nodejs.org/)

[![Windows](https://img.shields.io/badge/Windows-supported-blue.svg)](#supported-platforms)
[![macOS](https://img.shields.io/badge/macOS-supported-blue.svg)](#supported-platforms)
[![Linux](https://img.shields.io/badge/Linux-supported-blue.svg)](#supported-platforms)

[![Claude Code](https://img.shields.io/badge/Claude_Code-supported-blueviolet.svg)](#supported-agents)
[![Cursor](https://img.shields.io/badge/Cursor-supported-blueviolet.svg)](#supported-agents)
[![Codex](https://img.shields.io/badge/Codex-supported-blueviolet.svg)](#supported-agents)
[![opencode](https://img.shields.io/badge/opencode-supported-blueviolet.svg)](#supported-agents)
[![Hermes Agent](https://img.shields.io/badge/Hermes_Agent-supported-blueviolet.svg)](#supported-agents)
[![Gemini](https://img.shields.io/badge/Gemini-supported-blueviolet.svg)](#supported-agents)
[![Antigravity](https://img.shields.io/badge/Antigravity-supported-blueviolet.svg)](#supported-agents)
[![Kiro](https://img.shields.io/badge/Kiro-supported-blueviolet.svg)](#supported-agents)

<br>

**CodeGraph 平台即将到来** — 对每一个 PR，精确知道要测试什么、什么可能出问题、哪些流程受影响、以及业务逻辑是否受损。

<a href="https://getcodegraph.com"><img alt="加入早期 Beta 访问候补名单" src="https://raw.githubusercontent.com/colbymchenry/codegraph/main/assets/waitlist.svg" height="44"></a>

<sub>获取 <b>早期 Beta 访问</b> 托管产品 · <a href="https://getcodegraph.com">getcodegraph.com</a></sub>

</div>

## 开始使用

### 1. 安装 CLI

**无需 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
```

已安装 Node？使用 npm 替代（适用于任何版本）：

```bash
npm i -g @colbymchenry/codegraph
```

<sub>CodeGraph 捆绑了自己的运行时 — 无需编译，无需原生构建，在所有平台运行一致。安装程序会将 `codegraph` 添加到您的 PATH，但**不会改变当前 shell** — 下一步前请打开新终端，以便命令能够解析。</sub>

### 2. 配置您的 agent

在**新终端**中，运行安装程序以将 CodeGraph 连接到您使用的 agent：

```bash
codegraph install
```

<sub>自动检测并配置 Claude Code、Cursor、Codex CLI、opencode、Hermes Agent、Gemini CLI、Antigravity IDE 和 Kiro — 将 CodeGraph MCP 服务器接入每个 agent。**这一步是将 CodeGraph 连接到您的 agent 的关键；** 仅执行步骤 1 的 CLI 安装不会自动完成连接。（快捷方式：`npx @colbymchenry/codegraph` 一步完成下载和运行。）</sub>

### 3. 初始化每个项目

```bash
cd your-project
codegraph init -i
```

<sub>`codegraph init` 仅创建本地的 `.codegraph/` 索引目录；添加 `-i`（`--index`）会在同一步骤中构建初始图。如果不加 `-i`，之后运行 `codegraph index` 来填充索引。</sub>

<div align="center">

![1_C_VYnhpys0UHrOuOgpgoyw](https://github.com/user-attachments/assets/f168182f-4d9a-44e0-94d7-08d018cc8a3a)

</div>

### 卸载

改变主意了？一条命令即可从每个已配置的 agent 中移除 CodeGraph：

```bash
codegraph uninstall
```

<sub>撤销安装程序 — 从每个已配置 agent 中移除 CodeGraph 的 MCP 服务器配置、指令和权限。您的项目索引（`.codegraph/`）保持不变；使用 `codegraph uninit` 逐个项目删除。使用 `--target` 从特定 agent 中移除，或使用 `--yes` 以非交互方式运行。</sub>

---

## 为什么选择 CodeGraph？

当 Claude Code 探索代码库时，它会启动 **Explore agent** 来使用 grep、glob 和 Read 扫描文件 — 每次工具调用都会消耗 token。

**CodeGraph 为这些 agent 提供预索引的知识图谱** — 符号关系、调用图和代码结构。Agent 可即时查询图谱，而无需扫描文件。

### 基准测试结果

在涵盖 7 种语言的 **7 个真实开源代码库**上测试，比较一个 agent（Claude Code，无头模式）在**有**和**没有** CodeGraph 的情况下回答一个架构问题的表现。每个单元格显示每个测试组 4 次运行中位数的节省值。*在 Opus 4.8（2026-06-02）上重新验证，使用当前构建版本（`codegraph_explore` 作为主要工具）。*

> **平均：便宜 16% · 减少 47% token · 快 22% · 减少 58% 工具调用**

| 代码库 | 语言 | 成本 | Token | 时间 | 工具调用 |
|----------|----------|------|--------|------|------------|
| **VS Code** | TypeScript · ~10k 文件 | 便宜 18% | 减少 64% | 快 11% | 减少 81% |
| **Excalidraw** | TypeScript · ~640 | 持平 | 减少 25% | 快 27% | 减少 40% |
| **Django** | Python · ~3k | 便宜 8% | 减少 60% | 快 13% | 减少 77% |
| **Tokio** | Rust · ~790 | 持平 | 减少 38% | 快 18% | 减少 57% |
| **OkHttp** | Java · ~645 | 便宜 25% | 减少 54% | 快 31% | 减少 50% |
| **Gin** | Go · ~110 | 便宜 19% | 减少 23% | 快 24% | 减少 44% |
| **Alamofire** | Swift · ~110 | 便宜 40% | 减少 64% | 快 33% | 减少 58% |

CodeGraph 在**每个代码库**上削减了 **token、工具调用和实际时间** — 无论代码库是小型、中型还是大型 — 并且以**近乎零文件读取**的方式回答问题，而没有 CodeGraph 的 agent 则将其预算消耗在 grep/find/Read 发现上。`codegraph_explore` 完整展示答案 — 机制加上您询问的确切方法，即使它们深埋在数千行代码的文件中 — 同时将冗余的可互换实现折叠为签名，因此响应的大小取决于*答案*而不是文件数量。**成本在所有地方保持持平或更便宜** — 小型代码库（Alamofire、OkHttp）节省最多，在响应最密集的代码库（Excalidraw、Tokio）大致持平，在这些地方 CodeGraph 用几次大型的、缓存密集型的工具响应取代了无 CodeGraph agent 的许多小型 grep/read 往返。

<details>
<summary><strong>每个代码库详细对比 — WITH（有）vs WITHOUT（无）（4次运行中位数）</strong></summary>

**VS Code** · ~10k 文件
| 指标 | 有 CG | 无 CG | Δ |
|---|---|---|---|
| 时间 | 1分 59秒 | 2分 13秒 | 快 11% |
| 文件读取 | 0 | 9 | −9 |
| Grep/Bash | 0 | 11 | −11 |
| 工具调用 | 4 | 21 | 减少 81% |
| 总 token | 640k | 1.79M | 减少 64% |
| 成本 | $0.68 | $0.83 | 便宜 18% |

**Excalidraw** · ~640 文件
| 指标 | 有 CG | 无 CG | Δ |
|---|---|---|---|
| 时间 | 1分 32秒 | 2分 6秒 | 快 27% |
| 文件读取 | 0 | 7 | −7 |
| Grep/Bash | 1 | 8 | −7 |
| 工具调用 | 9 | 15 | 减少 40% |
| 总 token | 1.27M | 1.69M | 减少 25% |
| 成本 | $0.78 | $0.78 | 持平 |

**Django** · ~3k 文件
| 指标 | 有 CG | 无 CG | Δ |
|---|---|---|---|
| 时间 | 1分 43秒 | 1分 58秒 | 快 13% |
| 文件读取 | 0 | 9 | −9 |
| Grep/Bash | 0 | 5 | −5 |
| 工具调用 | 3 | 13 | 减少 77% |
| 总 token | 559k | 1.41M | 减少 60% |
| 成本 | $0.57 | $0.62 | 便宜 8% |

**Tokio** · ~790 文件
| 指标 | 有 CG | 无 CG | Δ |
|---|---|---|---|
| 时间 | 1分 55秒 | 2分 20秒 | 快 18% |
| 文件读取 | 0 | 8 | −8 |
| Grep/Bash | 0 | 6 | −6 |
| 工具调用 | 6 | 14 | 减少 57% |
| 总 token | 1.08M | 1.73M | 减少 38% |
| 成本 | $0.82 | $0.82 | 持平 |

**OkHttp** · ~645 文件
| 指标 | 有 CG | 无 CG | Δ |
|---|---|---|---|
| 时间 | 1分 1秒 | 1分 29秒 | 快 31% |
| 文件读取 | 0 | 4 | −4 |
| Grep/Bash | 2 | 6 | −4 |
| 工具调用 | 5 | 10 | 减少 50% |
| 总 token | 502k | 1.10M | 减少 54% |
| 成本 | $0.41 | $0.55 | 便宜 25% |

**Gin** · ~110 文件
| 指标 | 有 CG | 无 CG | Δ |
|---|---|---|---|
| 时间 | 1分 14秒 | 1分 37秒 | 快 24% |
| 文件读取 | 1 | 6 | −5 |
| Grep/Bash | 1 | 2 | −1 |
| 工具调用 | 5 | 9 | 减少 44% |
| 总 token | 651k | 847k | 减少 23% |
| 成本 | $0.46 | $0.57 | 便宜 19% |

**Alamofire** · ~110 文件
| 指标 | 有 CG | 无 CG | Δ |
|---|---|---|---|
| 时间 | 1分 35秒 | 2分 21秒 | 快 33% |
| 文件读取 | 0 | 9 | −9 |
| Grep/Bash | 0 | 4 | −4 |
| 工具调用 | 5 | 12 | 减少 58% |
| 总 token | 766k | 2.10M | 减少 64% |
| 成本 | $0.57 | $0.95 | 便宜 40% |

</details>

<details>
<summary><strong>完整基准测试详情</strong></summary>

**方法论。** 每个测试组以 `claude -p`（Claude Opus 4.8）方式无头运行，使用 `--strict-mcp-config`：**有** = 启用 CodeGraph 的 MCP 服务器，**无** = 空 MCP 配置。内置的 Read/Grep/Bash 双方均可使用。每个代码库相同问题，**每个测试组 4 次运行，报告中位数**。成本 = 运行的 `total_cost_usd`；Token = 处理的总 token（输入（含缓存）+ 输出）；时间 = 实际耗时；工具调用 = 每次工具调用，包括模型生成的任何子 agent 内的调用。代码库以 `--depth 1` 克隆，并由提供服务的同一 CodeGraph 构建版本索引。2026-06-02 在当前构建版本上重新验证。这些数字低于之前的 Opus 4.7 验证 — 不是 CodeGraph 的回退，而是更强的原生基线：Opus 4.8 在主线程上高效 grep/read，而不是分散到大型 Explore 子 agent 扫描中，因此无 CodeGraph 测试组比以前更精简。每个代码库的数字会因无 CodeGraph 测试组的激烈程度而变化（4次运行中位数平滑了差异，但尾部仍然存在 — 例如 Django 的无 CodeGraph 测试组在某批处理中达到了 $2.71/14m）。

**查询：**
| 代码库 | 查询 |
|----------|-------|
| VS Code | "扩展主机如何与主进程通信？" |
| Excalidraw | "Excalidraw 如何渲染和更新画布元素？" |
| Django | "Django 的 ORM 如何从 QuerySet 构建和执行查询？" |
| Tokio | "tokio 如何在其运行时上调度和执行异步任务？" |
| OkHttp | "OkHttp 如何通过其拦截器链处理请求？" |
| Gin | "gin 如何通过其中间件链路由请求？" |
| Alamofire | "Alamofire 如何构建、发送和验证请求？" |

**为什么 CodeGraph 胜出：** 索引可用时，agent 直接回答 — 通常一次 `codegraph_explore` 返回相关源码 — 然后停止，通常零文件读取。没有它，agent 将其大部分预算花在发现上（find/ls/grep），然后才读取正确的代码。CodeGraph 仅在*直接*查询时才有帮助，因此其指令引导 agent 直接回答，而不是将探索委托给文件读取子 agent — 否则子 agent 无论如何都会读取文件，CodeGraph 反而成为负担。

</details>

---

## 主要功能

| | |
|---|---|
| **智能上下文构建** | 一次工具调用返回入口点、相关符号和代码片段 — 无需昂贵的探索 agent |
| **全文搜索** | 在整个代码库中按名称即时查找代码，基于 FTS5 驱动 |
| **影响分析** | 在进行更改前追踪调用者、被调用者以及任何符号的完整影响范围 |
| **始终保持最新** | 文件监视器使用原生操作系统事件（FSEvents/inotify/ReadDirectoryChangesW），带防抖自动同步 — 图谱随您编码保持最新，零配置 |
| **20+ 种语言** | TypeScript、JavaScript、Python、Go、Rust、Java、C#、PHP、Ruby、C、C++、Objective-C、Swift、Kotlin、Dart、Lua、Luau、Svelte、Liquid、Pascal/Delphi |
| **框架感知路由** | 识别 Web 框架路由文件，将 URL 模式链接到其处理器，支持 14 个框架 |
| **混合 iOS / React Native / Expo** | 闭合静态解析遗漏的跨语言流程：Swift ↔ ObjC 桥接、React Native 遗留桥接 + TurboModules + Fabric 视图组件、原生 → JS 事件发射器、Expo Modules |
| **100% 本地化** | 没有数据离开您的机器。无需 API 密钥。无需外部服务。仅有 SQLite 数据库 |

<details>
<summary><strong>自动同步的工作原理 — 以及为什么您不需要手动运行 <code>codegraph sync</code></strong></summary>

当您的 agent（Claude Code、Cursor、Codex、opencode）启动 `codegraph serve --mcp` 时，三个层协同工作，使索引与您的代码保持同步 — 并确保 agent 在编辑和下一次同步之间的短暂窗口中不会收到静默错误的答案：

1. **带防抖自动同步的文件监视器。** 原生 FSEvents / inotify / ReadDirectoryChangesW 监视器捕获每次源文件的创建/修改/删除，并在防抖窗口（默认 `2000ms`，可通过 `CODEGRAPH_WATCH_DEBOUNCE_MS` 调节，限制在 `[100ms, 60s]`）后触发重新索引。批量编辑会合并为一次同步。

2. **每个文件的陈旧性提示。** 在短暂的防抖窗口期间，引用仍待处理文件的 MCP 工具响应会在前面加上一个 `⚠️` 横幅，命名该文件并告知 agent 直接 `Read` 它。响应中**未**引用的待处理文件会以小页脚形式显示。无论哪种方式，agent 都会收到明确的信号 — 在与 Claude Code 的验证中，agent 会在打开文件前明确说"为获取实时内容直接读取该文件"。

3. **连接时追赶。** 当 MCP 服务器（重新）连接时，codegraph 在回答第一个查询之前，会对工作树运行快速的 `(size, mtime)` + 内容哈希校验 — 这样在没有 MCP 服务器运行时所做的编辑（终端的 `git pull`、其他编辑器的编辑、之前已退出的 agent 会话）会在下一会话的第一次工具调用时被吸收。

```
agent 写入 src/Widget.ts
  → 监视器触发（<100ms）
  → 防抖（默认 2s）
  → 同步；Widget.ts 已纳入索引
  → 下一次 agent 查询即可看到
```

**随时验证** 使用 `codegraph_status`（通过 MCP）或 `codegraph status`（CLI）。如果有任何待处理的内容，您会看到 `### 待同步：` 部分，列出文件名及其编辑时长。

需要手动 `codegraph sync` 的少数情况：监视器被禁用（沙盒环境，或设置了 `CODEGRAPH_NO_DAEMON=1`），或者您在 agent 会话之外对索引编写脚本，并希望在脚本开始时进行预同步。

→ 完整深入说明见 [指南 → 索引项目](https://colbymchenry.github.io/codegraph/guides/indexing/#stay-fresh-automatically)。

</details>

---

## 框架感知路由

CodeGraph 检测 Web 框架路由文件，并发出通过 `references` 边链接到其处理器类或函数的 `route` 节点。查询视图/控制器的调用者现在会显示绑定它的 URL 模式。

| 框架 | 识别的形态 |
|---|---|
| **Django** | `path()`、`re_path()`、`url()`、`include()` 在 `urls.py` 中（CBV `.as_view()`、点号路径） |
| **Flask** | `@app.route('/path', methods=[...])`、蓝图路由 |
| **FastAPI** | `@app.get(...)`、`@router.post(...)`、所有标准方法 |
| **Express** | `app.get(...)`、`router.post(...)` 带中间件链 |
| **NestJS** | `@Controller` + `@Get/@Post/...`、GraphQL `@Resolver` + `@Query/@Mutation`、`@MessagePattern`/`@EventPattern`、`@SubscribeMessage` |
| **Laravel** | `Route::get()`、`Route::resource()`、`Controller@action`、元组语法 |
| **Drupal** | `*.routing.yml` 路由（`_controller`、`_form`、实体处理器）；`.module`/`.theme`/`.install`/`.inc` 中的 `hook_*` 实现 |
| **Rails** | `get '/x', to: 'users#index'`、hash-rocket `=>` 语法 |
| **Spring** | `@GetMapping`、`@PostMapping`、`@RequestMapping` 在方法上 |
| **Gin / chi / gorilla / mux** | `r.GET(...)`、`router.HandleFunc(...)` |
| **Axum / actix / Rocket** | `.route("/x", get(handler))` |
| **ASP.NET** | 操作方法上的 `[HttpGet("/x")]` 属性 |
| **Vapor** | `app.get("x", use: handler)` |
| **React Router** / **SvelteKit** | 路由组件节点 |

---

## 混合 iOS / React Native / Expo 桥接

真实的 iOS 和 React Native 代码库跨越多种语言 — Swift 调用者调用已自动桥接的 Objective-C 选择器，JS 文件通过 React Native 桥接调用原生模块，JSX 组件委托给原生视图管理器。静态 tree-sitter 提取在每个语言边界处停止。CodeGraph 桥接它们，使 `trace`、`callers`、`callees` 和 `impact` 能够端到端地跨越间隙进行连接。

| 边界 | JS/Swift 端 | 原生端 | 方式 |
|---|---|---|---|
| **Swift → ObjC** | Swift `obj.foo(bar:)` | ObjC 选择器 `-fooWithBar:` | `@objc` 自动桥接规则（包括 init/property/protocol 形式）+ Cocoa 介词前缀（`With`/`For`/`By`/`In`/`On`/`At`/…） |
| **ObjC → Swift** | ObjC `[obj fooWithBar:]` | Swift `@objc func foo(bar:)` | 反向桥接名称候选；从源码验证 `@objc` 暴露 |
| **React Native 遗留桥接** | JS `NativeModules.X.fn(...)` | ObjC `RCT_EXPORT_METHOD` / `RCT_REMAP_METHOD` · Java/Kotlin `@ReactMethod` | 解析宏/注解声明以构建 JS 名称 → 原生方法映射 |
| **React Native TurboModules** | JS `import M from './NativeM'; M.fn(...)` | 匹配 Codegen 规范的原生实现 | 以 `Native<X>.ts` 规范接口为基准 |
| **RN 原生 → JS 事件** | JS `new NativeEventEmitter(...).addListener('e', cb)` | ObjC `[self sendEventWithName:@"e" body:...]` · Swift `sendEvent(withName: "e", ...)` · Java/Kotlin `.emit("e", ...)` | 以字面事件名称为键的合成跨语言事件通道 |
| **Expo Modules** | JS `requireNativeModule('X').fn(...)` | Swift / Kotlin `Module { Name("X"); AsyncFunction("fn") { ... } }` | 解析 Expo DSL 字面量；合成方法节点通过现有名称匹配解析 |
| **Fabric 视图组件** | JSX `<MyView prop={v}/>` | TS Codegen 规范 + 原生实现类 | 规范 → `component` 节点；基于约定的名称+suffix 查找（`View`/`ComponentView`/`Manager`/`ViewManager`）桥接到原生 |
| **遗留 Paper 视图管理器** | JSX `<MyView prop={v}/>` | ObjC `RCT_EXPORT_VIEW_PROPERTY` · Java/Kotlin `@ReactProp` | 与 Fabric 相同 — Paper 时代的声明也会生成 `component` + `property` 节点 |

**在真实代码库上验证**（每个桥接的小型 + 中型 + 大型）：

| 桥接 | 小型 | 中型 | 大型 |
|---|---|---|---|
| Swift ↔ ObjC | [Charts](https://github.com/danielgindi/Charts) | [realm-swift](https://github.com/realm/realm-swift) | [Wikipedia-iOS](https://github.com/wikimedia/wikipedia-ios) |
| RN 遗留桥接 | [AsyncStorage](https://github.com/react-native-async-storage/async-storage) | [react-native-svg](https://github.com/software-mansion/react-native-svg) | [react-native-firebase](https://github.com/invertase/react-native-firebase) |
| RN 原生 → JS 事件 | [RNGeolocation](https://github.com/Agontuk/react-native-geolocation-service) | — | react-native-firebase |
| Expo Modules | expo-haptics | expo-camera | expo SDK 扫描（7 个包） |
| Fabric / Paper 视图 | [react-native-segmented-control](https://github.com/react-native-segmented-control/segmented-control) | [react-native-screens](https://github.com/software-mansion/react-native-screens) | [react-native-skia](https://github.com/Shopify/react-native-skia) |

每个桥接发出标记为 `provenance:'heuristic'` 的边，带有 `metadata.synthesizedBy:` 设置为稳定的通道名称（例如 `swift-objc-bridge`、`rn-event-channel`、`fabric-native-impl`、`expo-module-extract`），这样 agent 可以一目了然地看到跳转是如何进入图谱的。

---

## 快速开始

### 1. 运行安装程序

```bash
npx @colbymchenry/codegraph
```

安装程序将：
- 询问要配置哪些 agent — 自动检测已安装的：**Claude Code**、**Cursor**、**Codex CLI**、**opencode**、**Hermes Agent**、**Gemini CLI**、**Antigravity IDE**、**Kiro**
- 提示将 `codegraph` 安装到 PATH（这样 agent 可以启动 MCP 服务器）
- 询问配置适用于所有项目还是仅当前项目
- 为每个选中的 agent 写入 MCP 服务器配置（codegraph 使用指南由 MCP 服务器本身提供，因此不会向 `CLAUDE.md` / `AGENTS.md` 等添加指令文件）
- 当 Claude Code 是目标之一时，设置自动允许权限
- 初始化当前项目（仅本地安装）

**非交互式（脚本/CI）：**

```bash
codegraph install --yes                              # 自动检测 agent，全局安装
codegraph install --target=cursor,claude --yes       # 明确目标列表
codegraph install --target=auto --location=local     # 检测到的 agent，项目本地
codegraph install --print-config codex               # 打印片段，不写入文件
```

| 标志 | 值 | 默认 |
|---|---|---|
| `--target` | `auto`、`all`、`none` 或 csv（`claude,cursor,...`） | 提示 |
| `--location` | `global`、`local` | 提示 |
| `--yes` | （布尔值） | 每一步都提示 |
| `--no-permissions` | （布尔值）跳过 Claude 自动允许列表 | 启用权限 |
| `--print-config <id>` | 为一个 agent 转储片段并退出 | — |

### 2. 重启您的 Agent

重启您的 agent（Claude Code / Cursor / Codex CLI / opencode / Hermes Agent / Gemini CLI / Antigravity IDE / Kiro）以加载 MCP 服务器。

### 3. 初始化项目

```bash
cd your-project
codegraph init -i
```

构建每个项目的知识图谱索引。一次全局 `codegraph install` 在您打开的每个项目中都能工作 — 无需为每个项目重新运行安装程序。

就是这样 — 当 `.codegraph/` 目录存在时，您的 agent 将自动使用 CodeGraph 工具。

<details>
<summary><strong>手动设置（备选）</strong></summary>

**全局安装：**
```bash
npm install -g @colbymchenry/codegraph
```

**添加到 `~/.claude.json`：**
```json
{
  "mcpServers": {
    "codegraph": {
      "type": "stdio",
      "command": "codegraph",
      "args": ["serve", "--mcp"]
    }
  }
}
```

**添加到 `~/.claude/settings.json`（可选，用于自动允许）：**
```json
{
  "permissions": {
    "allow": [
      "mcp__codegraph__codegraph_search",
      "mcp__codegraph__codegraph_explore",
      "mcp__codegraph__codegraph_callers",
      "mcp__codegraph__codegraph_callees",
      "mcp__codegraph__codegraph_impact",
      "mcp__codegraph__codegraph_node",
      "mcp__codegraph__codegraph_status",
      "mcp__codegraph__codegraph_files"
    ]
  }
}
```

</details>

<details>
<summary><strong>Agent 工具指南</strong></summary>

CodeGraph 的 MCP 服务器在其 MCP `initialize` 响应中**自动**向您的 agent 传递使用指南 — 无需管理指令文件，也不会向您的 `CLAUDE.md` / `AGENTS.md` / `GEMINI.md` 添加任何内容。简而言之，它告诉 agent：

- **直接使用 CodeGraph 回答结构性问题** — 它*就是*预构建的索引，因此 grep/read 循环只是重复已做过的工作。将返回的源代码视为已读取。
- **按意图选择工具：** `codegraph_explore` 用于几乎任何情况 — "X 如何工作"、流程/"X 如何到达 Y"、或调查某个区域（一次调用返回按文件分组的相关符号源代码）；`codegraph_search` 仅用于定位符号；`codegraph_callers`/`codegraph_callees` 用于遍历调用流程；`codegraph_impact` 在编辑前使用；`codegraph_node` 用于获取一个特定符号的完整源代码（对不明确的名称返回每个重载）。
- **信任结果 — 不要用 grep 重新验证**，并在编辑后检查陈旧性提示。
- 如果 `.codegraph/` 不存在，提议运行 `codegraph init -i`。

确切文本在 `src/mcp/server-instructions.ts` — 单一事实来源。

</details>

---

## 工作原理

```
┌───────────────────────────────────────────────────────────────────┐
│                            Claude Code                            │
│                                                                   │
│   "请求如何到达数据库？"                                           │
│       直接调用 CodeGraph 工具 — 无需 Explore 子 agent              │
│                                 │                                 │
└─────────────────────────────────┬─────────────────────────────────┘
                                  │
                                  ▼
┌───────────────────────────────────────────────────────────────────┐
│                        CodeGraph MCP 服务器                        │
│                                                                   │
│       explore · search · callers · callees · impact · node        │
│                                 │                                 │
│                                 ▼                                 │
│                       SQLite 知识图谱                              │
│          符号 · 边 · 文件 · FTS5 全文搜索                         │
└───────────────────────────────────────────────────────────────────┘
```

1. **提取** — [tree-sitter](https://tree-sitter.github.io/) 将源代码解析为 AST。语言特定的查询提取节点（函数、类、方法）和边（调用、导入、扩展、实现）。

2. **存储** — 所有内容进入本地的 SQLite 数据库（`.codegraph/codegraph.db`），带有 FTS5 全文搜索。

3. **解析** — 提取后，解析引用：函数调用 → 定义、导入 → 源文件、类继承以及框架特定模式。

4. **自动同步** — MCP 服务器使用原生操作系统文件事件监视您的项目。变更被防抖处理（2秒静默窗口）、过滤到仅源文件、并增量同步。图谱随您编码保持最新 — 无需配置。

---

## CLI 参考

```bash
codegraph                         # 运行交互式安装程序
codegraph install                 # 运行安装程序（显式）
codegraph uninstall               # 从您的 agent 中移除 CodeGraph（安装的逆操作）
codegraph init [path]             # 在项目中初始化（--index 也进行索引）
codegraph uninit [path]           # 从项目中移除 CodeGraph（--force 跳过提示）
codegraph index [path]            # 完整索引（--force 重新索引，--quiet 减少输出）
codegraph sync [path]             # 增量更新
codegraph status [path]           # 显示统计信息
codegraph query <search>          # 搜索符号（--kind、--limit、--json）
codegraph files [path]            # 显示文件结构（--format、--filter、--max-depth、--json）
codegraph callers <symbol>        # 查找什么调用了函数/方法（--limit、--json）
codegraph callees <symbol>        # 查找函数/方法调用了什么（--limit、--json）
codegraph impact <symbol>         # 分析更改符号会影响哪些代码（--depth、--json）
codegraph affected [files...]     # 查找受更改影响的测试文件（见下文）
codegraph serve --mcp             # 启动 MCP 服务器
```

### `codegraph affected`

递归追踪导入依赖，查找哪些测试文件受更改的源文件影响。

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

| 选项 | 描述 | 默认 |
|--------|-------------|---------|
| `--stdin` | 从标准输入读取文件列表 | `false` |
| `-d, --depth <n>` | 最大依赖遍历深度 | `5` |
| `-f, --filter <glob>` | 用于识别测试文件的自定义 glob | 自动检测 |
| `-j, --json` | 输出为 JSON | `false` |
| `-q, --quiet` | 仅输出文件路径 | `false` |

**CI/hook 示例：**

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

---

## MCP 工具

作为 MCP 服务器运行时，CodeGraph 向 Claude Code 暴露以下工具：

| 工具 | 用途 |
|------|---------|
| `codegraph_explore` | **主要工具。** 一次调用回答几乎任何问题 — "X 如何工作"、流程（"X 如何到达 Y"）、或调查某个区域 — 返回按文件分组的相关符号的原始源代码，以及关系图和影响范围。能发现 grep 无法追踪的动态分发跳转（回调、React 重新渲染、接口→实现）。 |
| `codegraph_search` | 在整个代码库中按名称查找符号 |
| `codegraph_callers` | 查找什么调用了函数 |
| `codegraph_callees` | 查找函数调用了什么 |
| `codegraph_impact` | 分析更改符号会影响哪些代码 |
| `codegraph_node` | 获取一个特定符号的详细信息 + 完整源代码（对不明确的名称返回每个重载） |
| `codegraph_files` | 获取已索引的文件结构（比文件系统扫描更快） |
| `codegraph_status` | 检查索引健康状况和统计信息 |

---

## 库使用

CodeGraph 可以直接嵌入。npm 包重新导出其编程 API，因此 `import` 和 `require` 都能在您自己的进程中解析 `CodeGraph` 类 — 便于嵌入到应用程序中（例如 Electron 主进程）。

```typescript
import CodeGraph from '@colbymchenry/codegraph';
// CommonJS 也可以：
//   const { CodeGraph } = require('@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();
```

从同一入口点导出了更底层的构建块，供直接驱动图谱的调用者使用：`DatabaseConnection`、`QueryBuilder`、`getDatabasePath`、`initGrammars` / `loadGrammarsForLanguages` 和 `FileLock`。

**嵌入要求**

- 从 npm 安装（`npm i @colbymchenry/codegraph`），以便匹配的每个平台包 — 包含编译后的库及其依赖 — 与 shim 一起被获取。
- API 在**您**的运行时上运行，因此需要 **Node 22.5+** 以使用内置的 `node:sqlite`（当 Electron 捆绑的 Node 版本为 22.5+ 时符合条件）。CLI 和 MCP 服务器不受影响 — 它们在自包含的捆绑运行时上运行。
- TypeScript 类型随包一起提供。与任何面向 Node 的库一样，保持 `@types/node` 可用并设置 `skipLibCheck: true`（常见默认值）。

---

## 配置

没有任何配置 — CodeGraph 是零配置，**无需编写或维护配置文件**。语言支持根据文件扩展名自动确定，无需为每种语言做任何配置。

默认排除的内容：

- **依赖、构建和缓存目录** — `node_modules`、`vendor`、`dist`、`build`、`target`、`.venv`、`Pods`、`.next` 等，涵盖所有[支持的栈](#supported-languages) — 因此图谱是您的代码，而不是第三方噪音。即使没有 `.gitignore` 也是如此。
- **您 `.gitignore` 中的任何内容** — 在 git 仓库中通过 git 实现，在非 git 项目中通过直接读取 `.gitignore`（根目录和嵌套）实现。
- **大于 1 MB 的文件** — 生成包、压缩后的 JS、打包的 blob。

要排除其他内容，将其添加到 `.gitignore`。要将默认排除的目录重新**纳入**（例如您确实想要索引一个打包的依赖），添加否定规则 — `!vendor/`。默认设置统一应用，因此提交依赖或构建目录不会强制其进入图谱；`.gitignore` 否定规则是显式的选择加入。

## 支持平台

每个版本都发布自包含构建（捆绑 Node 运行时 — 无需编译），适用于所有三种桌面操作系统，包括 Intel/AMD（x64）和 ARM（arm64）：

| 平台 | 架构 | 安装方式 |
|----------|---------------|---------|
| Windows | x64, arm64 | PowerShell 安装程序或 npm |
| macOS | x64, arm64 | shell 安装程序或 npm |
| Linux | x64, arm64 | shell 安装程序或 npm |

参见[开始使用](#开始使用)获取一行命令的安装指令。

## 支持的 Agent

交互式安装程序自动检测并配置以下每个 agent — 接入 MCP 服务器（它提供自己的使用指南，因此不会写入指令文件）：

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

## 支持的语言

| 语言 | 扩展名 | 状态 |
|----------|-----------|--------|
| TypeScript | `.ts`, `.tsx` | 完全支持 |
| JavaScript | `.js`, `.jsx`, `.mjs` | 完全支持 |
| Python | `.py` | 完全支持 |
| Go | `.go` | 完全支持 |
| Rust | `.rs` | 完全支持 |
| Java | `.java` | 完全支持 |
| C# | `.cs` | 完全支持 |
| PHP | `.php` | 完全支持 |
| Ruby | `.rb` | 完全支持 |
| C | `.c`, `.h` | 完全支持 |
| C++ | `.cpp`, `.hpp`, `.cc` | 完全支持 |
| Objective-C | `.m`, `.mm`, `.h` | 部分支持（类、协议、方法、`@property`、`#import`、消息发送；`.mm` ObjC++ 可能解析不完全） |
| Swift | `.swift` | 完全支持 |
| Kotlin | `.kt`, `.kts` | 完全支持 |
| Scala | `.scala`, `.sc` | 完全支持（类、特质、方法、类型别名、Scala 3 枚举） |
| Dart | `.dart` | 完全支持 |
| Svelte | `.svelte` | 完全支持（脚本提取、Svelte 5 runes、SvelteKit 路由） |
| Vue | `.vue` | 完全支持（script + script-setup 提取、Nuxt 页面/API/中间件路由） |
| Liquid | `.liquid` | 完全支持 |
| Pascal / Delphi | `.pas`, `.dpr`, `.dpk`, `.lpr` | 完全支持（类、记录、接口、枚举、DFM/FMX 表单文件） |
| Lua | `.lua` | 完全支持（函数、带接收者的方法、局部变量、`require` 导入、调用边） |
| Luau | `.luau` | 完全支持（Lua 的所有功能，加上 `type`/`export type` 别名、类型签名和 Roblox 实例路径 `require`） |

## 故障排除

**"CodeGraph 未初始化"** — 首先在项目目录中运行 `codegraph init`。

**索引缓慢** — 检查 `node_modules` 和其他大型目录是否被排除。使用 `--quiet` 减少输出开销。

**MCP 遇到 `database is locked`** — 当前构建版本不应该出现此问题：CodeGraph 捆绑了自己的 Node 运行时，并使用 Node 内置的 `node:sqlite`（WAL 模式），其中并发读取永远不会阻塞写入者。如果您仍然看到此问题：

- **您在使用旧（0.9 之前）安装版本。** 重新安装以获取捆绑运行时 — `curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh`（macOS/Linux）、`irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex`（Windows）、或 `npm i -g @colbymchenry/codegraph@latest`。
- **`codegraph status` 显示 `Journal:` 不是 `wal`** — 在此文件系统上无法启用 WAL（常见于网络共享和 WSL2 `/mnt`），因此读取可能会阻塞写入。将项目（连同其 `.codegraph/` 文件夹）移动到本地磁盘。

**MCP 服务器无法连接** — 确保项目已初始化/索引，验证 MCP 配置中的路径，并检查 `codegraph serve --mcp` 是否可以从命令行工作。

**符号缺失** — MCP 服务器在保存时自动同步（等待几秒钟）。如有需要，手动运行 `codegraph sync`。检查文件的语言是否受支持，并且不在 `.gitignore` 或默认排除的目录中（例如 `node_modules`、`dist`）。

## Star 历史

<a href="https://www.star-history.com/?repos=colbymchenry%2Fcodegraph&type=date&legend=top-left">
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=colbymchenry/codegraph&type=date&theme=dark&legend=top-left" />
   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=colbymchenry/codegraph&type=date&legend=top-left" />
   <img alt="Star 历史图表" src="https://api.star-history.com/chart?repos=colbymchenry/codegraph&type=date&legend=top-left" />
 </picture>
</a>

## 许可证

MIT

---

<div align="center">

**专为 AI 编码 agent 打造 — Claude Code、Cursor、Codex CLI、opencode、Hermes Agent、Gemini CLI、Antigravity IDE 和 Kiro**

[报告 Bug](https://github.com/colbymchenry/codegraph/issues) · [请求功能](https://github.com/colbymchenry/codegraph/issues)

</div>