# codegraph

**Repository Path**: goodsccd/codegraph

## Basic Information

- **Project Name**: codegraph
- **Description**: Pre-indexed code knowledge graph, auto syncs on code changes, for Claude Code, Codex, Gemini, Cursor, OpenCode, AntiGravity, Kiro, and Hermes Agent — fewer tokens, fewer tool calls, 100% local
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-04
- **Last Updated**: 2026-07-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">

# CodeGraph

## 🎉 1.0 已发布！

已安装？运行 `codegraph upgrade`

在 X 上关注 [@getcodegraph](https://x.com/getcodegraph) 获取更新。

### 用语义代码智能为 Claude Code、Cursor、Codex、OpenCode、Hermes Agent、Gemini、Antigravity 和 Kiro 注入强大动力

**精准上下文 · 更少工具调用 · 更快得到答案 · 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)](#支持平台)
[![macOS](https://img.shields.io/badge/macOS-supported-blue.svg)](#支持平台)
[![Linux](https://img.shields.io/badge/Linux-supported-blue.svg)](#支持平台)

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

<br>

**CodeGraph 平台即将上线** —— 针对每一个 PR，精准掌握：该测什么、可能崩在哪、哪些流程会受影响、业务逻辑是否被破坏。

<a href="https://getcodegraph.com"><img alt="加入候补名单，抢先体验 Beta" src="https://raw.githubusercontent.com/colbymchenry/codegraph/main/assets/waitlist.svg?v=2" height="52"></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
```

<details>
<summary><b>已经装了 Node？改用 npm（任意版本均可）</b></summary>

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

<sub>CodeGraph 自带运行时 —— 无需编译、无需原生构建，在各平台行为一致。安装程序会将 <code>codegraph</code> 加入你的 PATH，但<b>不会修改你当前的 shell</b> —— 在下一步之前请打开一个新终端，让命令生效。</sub>

<sub>随时可用 <code>codegraph upgrade</code> 升级 —— 它会自动识别你的安装方式（bundle、npm 或 npx）并就地更新。加 <code>--check</code> 可检查是否有更新，或用 <code>codegraph upgrade &lt;version&gt;</code> 锁定某个版本。</sub>

</details>

### 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 并不会自动完成接入。它只接入 agent —— **不会**索引任何代码；每个项目的图谱构建是第 3 步独立的 <code>codegraph init</code>。（快捷方式：<code>npx @colbymchenry/codegraph</code> 一步完成下载并运行。）</sub>

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

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

<sub>`codegraph init` 会创建本地 `.codegraph/` 目录并同时构建完整图谱 —— 一条命令搞定。</sub>

<div align="center">

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

</div>

### 4. 再也不用同步！

默认开启自动同步。CodeGraph 会监视项目，在你 agent 编辑代码、新增、修改或删除文件时即时更新图谱。**索引永远不会过期，也不需要重新运行任何命令。**

### 卸载

改主意了？一条命令即可从所有配置过的 agent 中移除 CodeGraph：

```bash
codegraph uninstall
```

<sub>与安装过程正好相反 —— 从每个配置过的 agent 中清除 CodeGraph 的 MCP 服务器配置、说明与权限。项目索引（<code>.codegraph/</code>）保持原样；如需按项目移除，请使用 <code>codegraph uninit</code>。可加 <code>--target</code> 仅从指定 agent 移除，或加 <code>--yes</code> 以非交互模式运行。</sub>

---

### 5. **跨分支差异巨大

```
codegraph index --force
```

|                        |                                  |
| ---------------------- | -------------------------------- |
| **跨分支差异巨大**（结构变化、语言变化） | 跑 `codegraph index --force` 全量重建 |
## 为什么选择 CodeGraph？

当 AI agent 需要理解代码 —— 无论是回答一个提问还是做一次改动 —— 它都会用最笨的方式去发现结构：grep、glob、Read，一次一个文件，手工重建调用路径和依赖关系。在真正开始干活之前，就先堆出了一大堆工具调用和往返开销。

**CodeGraph 让 agent 一次调用就拿到它所需的精确代码。** 它是一张预先构建好的知识图谱，覆盖你代码库中的每一个符号、调用边和依赖 —— agent 不再需要逐个文件地翻找，而是直接发问，就能拿到相关源码、符号之间的调用路径（包括 grep 无法跟踪的动态分发跳转），以及一次改动的爆炸半径。**精准的上下文，而不是逐文件搜索** —— 这意味着在任何规模的代码库上，工具调用都更少、答案都更快。

<img width="1536" height="1024" alt="token-cost-savings-scale" src="https://github.com/user-attachments/assets/eb74a11a-a3ab-4b01-80a6-19f78352ae8e" />

> **关于成本的一点说明：** CodeGraph 在*任何*代码库上的胜利都是精准与速度 —— 工具调用更少、答案更快。它也能降低 token 和金钱成本，但这份节省是**与规模相关的**：在体量适中的代码库上小而有噪，只有当仓库够大、纠缠够多时才显著 —— 在 Google、Microsoft 那种单体仓库的规模，再乘以整个团队每天的 agent 用量 —— 才会累加成真正的一笔账。在 500 文件的项目上，请为速度而采用 CodeGraph；成本节省要等代码库（和团队）变大了才会显现。

### 基准测试结果

横跨 **7 个真实开源代码库**、覆盖 7 种语言，对比一个 agent（Claude Code，headless 模式）在**有**和**无** CodeGraph 的情况下回答同一个架构问题，**每臂取 4 次运行的中位数**。_已于 2026-06-02 在 Opus 4.8 上、在当前构建版本（以 `codegraph_explore` 为主工具）重新验证。_

> **每一项的通用胜利 —— 不分仓库、不分规模：工具调用少 58% · 速度快 22% · 文件读取接近归零。**

最可靠、最通用的回报是**精准上下文与速度**：CodeGraph 把 agent 的 grep/find/Read 翻找压成几次直接查询 —— 即便你想要的方法深埋在数千行的文件里也能精确返回 —— 因此它以**近乎零的文件读取**给出答案，而无 CodeGraph 的 agent 却把预算花在了"找代码"上。**Tokens** 与 **Cost** 两列也是真实的，但 —— 如前所述 —— 它们**与规模相关**：单次查询上小而有噪，只有在大代码库、高调用量的规模下才会累积成真金白银。

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

<sub>**文件读取** = agent 在**有**vs**无** CodeGraph 下打开的文件数中位数 —— 一列讲清"精准上下文"的胜利。**Tokens** 与 **Cost** 同样是有 vs 无的差值；它们只是方向性指标（每次运行都会波动），且按单次查询绝对值都较小 —— 因此只有规模上去才会计成一笔账。<code>codegraph_explore</code> 还会把冗余的可互换实现折叠为签名，让响应的体量与*答案*相称，而不是与文件数相称。</sub>

<details>
<summary><strong>每个仓库的明细 —— 有 vs 无（4 次中位数）</strong></summary>

**VS Code** · ~10k 文件
| 指标 | 有 cg | 无 cg | Δ |
|---|---|---|---|
| 耗时 | 1 分 59 秒 | 2 分 13 秒 | 快 11% |
| 文件读取 | 0 | 9 | −9 |
| Grep/Bash | 0 | 11 | −11 |
| 工具调用 | 4 | 21 | 少 81% |
| 总 tokens | 64 万 | 179 万 | 少 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% |
| 总 tokens | 127 万 | 169 万 | 少 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% |
| 总 tokens | 55.9 万 | 141 万 | 少 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% |
| 总 tokens | 108 万 | 173 万 | 少 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% |
| 总 tokens | 50.2 万 | 110 万 | 少 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% |
| 总 tokens | 65.1 万 | 84.7 万 | 少 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% |
| 总 tokens | 76.6 万 | 210 万 | 少 64% |
| 成本 | $0.57 | $0.95 | 便宜 40% |

</details>

<details>
<summary><strong>完整基准测试细节</strong></summary>

**方法。** 每臂都是 `claude -p`（Claude Opus 4.8）以 headless 模式、带 `--strict-mcp-config` 在仓库上运行：**有** = 启用 CodeGraph 的 MCP 服务器，**无** = 空 MCP 配置。两边都可使用内置的 Read/Grep/Bash。每个仓库用同一个问题，**每臂跑 4 次，取中位数**。成本 = 该次运行的 `total_cost_usd`；Tokens = 处理的总 token（输入含缓存 + 输出）；耗时 = 墙钟时间；工具调用 = 每一次工具调用，包含模型派生的任何子 agent 内部的调用。仓库以 `--depth 1` 克隆，并由同一个对外服务的 CodeGraph 构建版本进行索引。于 2026-06-02 在当前构建上重新验证。这些数字低于此前 Opus 4.7 的验证 —— 并非 CodeGraph 退步，而是原生基线更强了：Opus 4.8 会在主线程上高效地 grep/read，而不是派出大型 Explore 子 agent 大扫一遍，所以"无 CodeGraph"那一臂比以前更精简了。每个仓库的数字会随"无"臂翻腾的剧烈程度波动（4 次取中位数已抚平波动，但极端值仍会出现 —— 比如 Django 的"无"臂在某批里冲到过 $2.71/14 分钟）。

**查询语句：**
| 代码库 | 查询 |
|----------|-------|
| 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>

---

## 核心特性

| | |
|---|---|
| **精准上下文** | 一次工具调用就返回入口点、相关符号和代码片段 —— 不再慢吞吞地逐文件探索 |
| **全文搜索** | 基于 FTS5，在全代码库上按名字瞬间定位代码 |
| **影响分析** | 在改动任何符号之前，追溯它的调用方、被调用方以及完整影响半径 |
| **始终新鲜** | 文件监听使用操作系统原生事件（FSEvents/inotify/ReadDirectoryChangesW），带防抖自动同步 —— 图谱随你编码实时更新，零配置 |
| **20+ 种语言** | TypeScript、JavaScript、Python、Go、Rust、Java、C#、VB.NET、PHP、Ruby、C、C++、CUDA、Objective-C、Metal、Swift、Kotlin、Scala、Dart、Lua、Luau、R、Erlang、CFML、COBOL、Solidity、Terraform/OpenTofu、Svelte、Vue、Astro、Liquid、Pascal/Delphi |
| **框架感知路由** | 识别 Web 框架的路由文件，跨 17 种框架把 URL 模式关联到对应处理器 |
| **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）
  → 防抖（默认 2 秒）
  → 同步；Widget.ts 进入索引
  → agent 的下一次查询能看到它
```

**随时可验证** —— 用 `codegraph status`（CLI）。如果有任何挂起项，你会看到一个 `### Pending sync:` 段落，列出文件名及其编辑距今时长。

少数适合手动 `codegraph sync` 的场景：监听器被禁用（沙箱环境，或设置了 `CODEGRAPH_NO_DAEMON=1`），或者你在 agent 会话之外针对索引写脚本，想在脚本开头预先同步一次。

→ 完整深入内容见 [Guides → Indexing a Project](https://colbymchenry.github.io/codegraph/guides/indexing/#stay-fresh-automatically)。

</details>

---

## 框架感知路由

CodeGraph 检测 Web 框架的路由文件，生成 `route` 节点，并通过 `references` 边连接到对应的处理器类或函数。查询某个 view/controller 的调用方时，现在能浮现出绑定它的 URL 模式。

| 框架 | 识别的形态 |
|---|---|
| **Django** | `urls.py` 中的 `path()`、`re_path()`、`url()`、`include()`（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`、entity handler）；`.module`/`.theme`/`.install`/`.inc` 中的 `hook_*` 实现 |
| **Rails** | `get '/x', to: 'users#index'`、`=>` 火箭符语法 |
| **Spring** | 方法上的 `@GetMapping`、`@PostMapping`、`@RequestMapping` |
| **Play** | `conf/routes` 中的 `GET`/`POST`/… 动词路由 → `Controller.method` action（Scala + Java） |
| **Gin / chi / gorilla / mux** | `r.GET(...)`、`router.HandleFunc(...)` |
| **Axum / actix / Rocket** | `.route("/x", get(handler))` |
| **ASP.NET** | action 方法上的 `[HttpGet("/x")]` 特性 |
| **Vapor** | `app.get("x", use: handler)` |
| **React Router** / **SvelteKit** | 路由组件节点 |
| **Vue Router** / **Nuxt** | `pages/` 文件式路由、`server/api/` 端点、路由中间件 |
| **Astro** | `src/pages/` 文件式路由（`.astro` 页面 + `.ts` 端点、`[param]`/`[...rest]` 语法） |

---

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

真实的 iOS 与 React Native 代码库横跨多种语言 —— 一段 Swift 调用了一个已被自动桥接的 Objective-C selector；某个 JS 文件通过 React Native 桥调用原生模块；某个 JSX 组件委托给原生 view manager。静态 tree-sitter 抽取在每个语言边界都会停下。CodeGraph 把这些边界桥接起来，让 `codegraph_explore` 跨越缝隙把流程端到端连上 —— 调用路径与爆炸半径会*穿过*边界，而不是停在那里。

| 边界 | JS / Swift 侧 | 原生侧 | 实现方式 |
|---|---|---|---|
| **Swift → ObjC** | Swift `obj.foo(bar:)` | ObjC selector `-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-name → 原生方法映射 |
| **React Native TurboModules** | JS `import M from './NativeM'; M.fn(...)` | 符合 Codegen 规范的原生实现 | 把 `Native<X>.ts` spec 接口视为真相来源 |
| **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 spec + 原生实现类 | spec → `component` 节点；基于约定的名字+后缀查找（`View`/`ComponentView`/`Manager`/`ViewManager`）桥接到原生 |
| **旧版 Paper view manager** | 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 服务器配置，并在 agent 的指引文件（`CLAUDE.md` / `AGENTS.md` / `GEMINI.md`）中追加一小段带标记围栏的 CodeGraph 区块 —— 这就是子 agent 和非 MCP 类 agent 学会 `codegraph explore` 命令的途径，因为 MCP 服务器自身的指引只会到达主 agent。`codegraph uninstall` 会干净地移除。
- 当 Claude Code 是目标之一时，设置自动放行权限

安装程序**只接入 agent —— 不会索引你的代码。** 它结束之后，请用 `codegraph init`（第 3 步）为每个项目构建图谱。一次全局的 `codegraph install` 适用于所有项目；而 `codegraph init` 需要每个项目各跑一次。

**非交互模式（脚本 / 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
```

构建按项目存储的知识图谱索引，之后每次文件改动都会自动同步。一次全局的 `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__*"
    ]
  }
}
```

<sub>一条通配符就自动放行所有 CodeGraph 工具 —— 默认只有 <code>codegraph_explore</code> 列出，但如果你通过 <code>CODEGRAPH_MCP_TOOLS</code> 重新启用其他工具，它们也已被允许，不会再弹提示。</sub>

</details>

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

CodeGraph 的 MCP 服务器会在 MCP `initialize` 响应中**自动**把使用指引送达你的 agent。简而言之，它会告诉 agent：

- **直接用 CodeGraph 回答结构性问题** —— 它*本身*就是预先构建好的索引，所以 grep/read 循环只是在重复它已经做过的工作。把返回的源码当作已读处理。
- **几乎凡事都先用 `codegraph_explore`** —— "X 是怎么工作的"、某个流程/"X 怎么到达 Y"、或考察一片区域。一次调用即可返回相关符号按文件分组的逐字源码、它们之间的调用路径（含动态分发跳转）以及爆炸半径摘要。在查询里点名某个文件或符号，就能读到它当前带行号的源码。
- **信任结果 —— 不要再用 grep 二次验证**，并在编辑后注意过期横幅。
- **按项目工作**：通过传 `projectPath` 查询任何有 `.codegraph/` 索引的项目 —— 这样一个只索引了部分服务的单体仓库，或第二个仓库，都能在同一个会话里使用。没有索引的路径会返回清晰的、引导使用内置工具的提示；建不建索引始终由你决定。

完整文本位于 `src/mcp/server-instructions.ts` —— 主 agent 的唯一真相来源。由于子 agent 与非 MCP 框架永远看不到 MCP 指引，安装程序也会在 agent 的指引文件里写一小段带标记围栏的区块，指向 CLI 的 `codegraph explore` 等价命令。

</details>

---

## 工作原理

```
┌───────────────────────────────────────────────────────────────────┐
│                            Claude Code                            │
│                                                                   │
│   "一个请求是如何到达数据库的？"                                  │
│       直接调用 CodeGraph 工具 —— 没有 Explore 子 agent            │
│                                 │                                 │
└─────────────────────────────────┴─────────────────────────────────┘
                                  │
                                  ▼
┌───────────────────────────────────────────────────────────────────┐
│                        CodeGraph MCP 服务器                       │
│                                                                   │
│ explore  ·  一次调用 → 逐字源码 + 调用流程 + 爆炸半径             │
│                                 │                                 │
│                                 ▼                                 │
│                       SQLite 知识图谱                             │
│          符号 · 边 · 文件 · FTS5 全文搜索                         │
└───────────────────────────────────────────────────────────────────┘
```

1. **抽取** —— [tree-sitter](https://tree-sitter.github.io/) 把源码解析为 AST。语言相关的查询抽取出节点（函数、类、方法）和边（调用、导入、继承、实现）。

2. **存储** —— 一切都写入本地 SQLite 数据库（`.codegraph/codegraph.db`），带 FTS5 全文搜索。

3. **解析** —— 抽取之后会进行引用解析：函数调用 → 定义、import → 源文件、类继承，以及框架相关的模式。

4. **自动同步** —— MCP 服务器使用 OS 原生文件事件监视你的项目。改动会经过防抖（2 秒静默窗口）、过滤（仅源码文件），然后增量同步。图谱随你编码实时新鲜 —— 无需任何配置。

---

## CLI 命令参考

```bash
codegraph                         # 运行交互式安装程序
codegraph install                 # 运行安装程序（显式）
codegraph uninstall               # 从你的 agent 中移除 CodeGraph（与 install 相反）
codegraph init [path]             # 初始化项目并构建图谱（一步完成）
codegraph uninit [path]           # 从项目中移除 CodeGraph（--force 跳过提示）
codegraph index [path]            # 全量索引（--force 重新索引，--quiet 减少输出）
codegraph sync [path]             # 增量更新
codegraph status [path]           # 显示统计信息
codegraph unlock [path]           # 移除阻碍索引的过期锁文件
codegraph query <search>          # 搜索符号（--kind、--limit、--json）
codegraph explore <query>         # 一次拿到相关符号源码 + 调用路径（与 codegraph_explore MCP 工具输出一致）
codegraph node <symbol|file>      # 单个符号的源码 + 调用方，或带行号读取文件（与 codegraph_node 输出一致）
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 daemon                  # 管理后台守护进程 —— 选一个停止（别名：daemons）
codegraph telemetry [on|off]      # 显示或更改匿名用量遥测
codegraph upgrade [version]       # 升级到最新版本（--check、--force）
codegraph version                 # 打印已安装版本（也可用 -v、--version）
codegraph help [command]          # 显示帮助，可选指定某条命令
```

### `codegraph affected`

传递地追踪 import 依赖，找出哪些测试文件会受改动的源文件影响。

```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` | 从 stdin 读取文件列表 | `false` |
| `-d, --depth <n>` | 最大依赖遍历深度 | `5` |
| `-f, --filter <glob>` | 用于识别测试文件的自定义 glob | 自动检测 |
| `-j, --json` | 以 JSON 输出 | `false` |
| `-q, --quiet` | 只输出文件路径 | `false` |

**CI / 钩子示例：**

```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 只暴露**一个工具** —— `codegraph_explore`。实测的 agent 行为显示：一个强力工具比一打窄工具更能引导 agent —— 错选更少，且每个会话都能节省上下文：

| 工具 | 用途 |
|------|---------|
| `codegraph_explore` | 一次调用回答几乎所有问题 —— "X 怎么工作"、某个流程（"X 如何到达 Y"）、或考察一片区域 —— 返回相关符号按文件分组的逐字源码、它们之间的调用路径，以及爆炸半径摘要。会暴露 grep 跟踪不到的动态分发跳转（回调、React 重渲染、interface→impl）。在查询里点名文件或符号，即可读到它当前带行号的源码，与 Read 工具的形态一致。 |

其余工具（`codegraph_node`、`codegraph_search`、`codegraph_callers`、`codegraph_callees`、`codegraph_impact`、`codegraph_files`、`codegraph_status`）依然完全可用，但**默认不列出** —— 它们返回的所有内容已经在 `codegraph_explore` 上内联呈现（它的爆炸半径段、关系图、某符号的函数体作为它的被调用方列表）。可通过 `CODEGRAPH_MCP_TOOLS` 环境变量为 MCP 表面重新启用其中任意工具（例如 `CODEGRAPH_MCP_TOOLS=explore,node,search,callers`），或使用它们的 CLI 等价命令（`codegraph node` / `query` / `callers` / `callees` / `impact` / `files` / `status`）。

即便服务器自身的根目录没有 `.codegraph/` 索引，工具也始终可用：传 `projectPath` 即可在同一会话里查询任何已索引的项目 —— 单体仓库中的某个子服务，或第二个仓库。没有索引的路径会返回清晰的、引导使用内置工具的提示，因此不会有任何东西报错失败，而是否索引仍由你决定。

---

## 作为库使用

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`），让配套的、携带编译好的库与依赖的 per-platform 包随 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` 等等，覆盖每一个[支持的技术栈](#支持的语言) —— 这样图谱里是你的代码，而不是第三方噪音。即使没有 `.gitignore` 也照样生效。
- **`.gitignore` 里列出的任何东西** —— 在 git 仓库里通过 git 来尊重，非 git 项目则直接读取 `.gitignore`（根目录与嵌套层级）。
- **大于 1 MB 的文件** —— 生成的 bundle、压缩过的 JS、第三方大块二进制。

想把别的东西也排除？加进 `.gitignore`。想把默认排除的目录重新拉**进来**（比如你确实想把某个 vendor 依赖纳入索引），加一条取反 —— `!vendor/`。默认规则一视同仁，所以把依赖或构建目录提交进仓库并不会强行让它进图谱；`.gitignore` 取反才是显式的 opt-in。

但 `.gitignore` 没法把已经**提交**进仓库的目录排除掉。对于 check-in 的第三方主题或 SDK（比如 `static/` 下的 Metronic 主题），把它列在 `codegraph.json` 的 `exclude` 下 —— gitignore 风格的模式，按"相对仓库根"路径匹配，在索引、同步、监听时一并尊重：

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

### 自定义文件扩展名

如果你的项目对某个[支持的语言](#支持的语言)使用了非标准扩展名 —— 比如用 `.dota_lua` 表示 Lua、用 `.tpl` 表示 PHP —— 这些文件默认会被跳过，因为该扩展名 CodeGraph 不认识。在项目根加一个可选的 **`codegraph.json`** 即可映射：

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

每个值是一个受支持的语言 id。该映射会叠加到内置默认之上，冲突时以你的为准，所以你也可以重新指派某个内置映射（例如 `".h": "cpp"`）。把这个文件提交进仓库即可与团队共享。语言名拼写错误或文件格式有问题都会被警告并跳过 —— 永远不会让索引崩溃 —— 没有 `codegraph.json` 的项目行为与之前完全一致。新增或修改映射后请重新索引（`codegraph index`）。

## 遥测

CodeGraph 收集**匿名使用统计** —— 哪些工具与命令被使用、哪些语言被索引 —— 以指导语言与 agent 支持的投入方向。**绝不**收集任何代码、路径、文件或符号名、查询内容或 IP 地址；用量先在本地聚合成每日总量，再发送任何东西，且采集端点就是[本仓库里的公开代码](telemetry-worker/)，强制执行文档所列的字段清单。安装程序会在最前面向你确认；随时可关：

```bash
codegraph telemetry off    # 或：CODEGRAPH_TELEMETRY=0，或 DO_NOT_TRACK=1
```

[`TELEMETRY.md`](TELEMETRY.md) 列出了每一个字段、关闭开关，以及完整的数据处理细节。

## 支持平台

每次发布都附带一个自包含构建（捆绑 Node 运行时 —— 无需编译），覆盖三种桌面 OS、x64 与 ARM（arm64）双架构：

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

一行安装命令见 [快速开始](#快速开始)。

## 支持的 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++ 解析可能不完整） |
| Metal | `.metal` | 完整支持（vertex/fragment/kernel 函数、struct、type alias、调用边 —— MSL 按 C++ 解析，并处理 `[[attribute]]` 注解） |
| CUDA | `.cu`, `.cuh` | 完整支持（kernel 与 device/host 函数、struct、class、通过 `<<<grid, block>>>` 启动语法的 host→kernel 调用边 —— 含模板化启动、函数指针启动（`auto kernel = &fn<...>`）、`dim3{...}` 配置和宏定义的 kernel；处理 `__global__`/`__device__`/`__launch_bounds__` 说明符；普通 `.h`/`.hpp` 头里的 CUDA 按内容识别） |
| Swift | `.swift` | 完整支持 |
| Kotlin | `.kt`, `.kts` | 完整支持 |
| Scala | `.scala`, `.sc` | 完整支持（class、trait、method、type alias、Scala 3 enum） |
| Dart | `.dart` | 完整支持 |
| Svelte | `.svelte` | 完整支持（script 抽取、Svelte 5 runes、SvelteKit 路由） |
| Vue | `.vue` | 完整支持（script + script-setup 抽取、Nuxt page/API/middleware 路由） |
| Astro | `.astro` | 完整支持（frontmatter + script 抽取、模板里的 component/call 引用、`src/pages/` 路由） |
| Liquid | `.liquid` | 完整支持 |
| Pascal / Delphi | `.pas`, `.dpr`, `.dpk`, `.lpr` | 完整支持（类、record、interface、enum、DFM/FMX form 文件） |
| Lua | `.lua` | 完整支持（函数、带 receiver 的方法、局部变量、`require` 导入、调用边） |
| R | `.R` `.r` | 完整支持（各种赋值形式中的函数、S4/R5/R6 类与方法、`library`/`require` 导入、`source()` 文件引用、调用边） |
| Luau | `.luau` | 完整支持（含 Lua 全部能力，外加 `type`/`export type` 别名、带类型签名、Roblox 实例路径 `require`） |
| CFML | `.cfc`, `.cfm`, `.cfs` | 完整支持（标签式 `<cfcomponent>`/`<cffunction>` 与裸脚本 `component { ... }` 风格、`extends`/`implements`、内嵌 `<cfscript>` 委托、调用边） |
| COBOL | `.cbl`, `.cob`, `.cpy` | 完整支持（program、section/paragraph 含 PERFORM/GO TO 调用边、CALL 'literal' 跨程序调用、COPY copybook 导入 —— 包括独立 `.cpy` 文件 —— DATA DIVISION 的 record/field/88-level、EXEC CICS LINK/XCTL 与 EXEC SQL INCLUDE 目标；固定格式与自由格式） |
| Visual Basic .NET | `.vb` | 完整支持（类、Module、interface、structure、enum、property、event、`Declare` P/Invoke、`Handles`/`WithEvents`、`Inherits`/`Implements` 边、穿过 VB 调用/索引括号歧义的调用边、`As New` 实例化、内插字符串、LINQ、Unicode 标识符） |
| Erlang | `.erl`, `.hrl`, `.escript`, `.app.src`, `.app` | 完整支持（多子句/多 arity 分组的函数、`-spec` 签名、带字段的 record、`-type`/`-opaque` 别名、`-define` 宏、`-include`/`-include_lib`/`-import` 边、本地与 `mod:fn` 远程调用边、`fun name/arity` 引用、`spawn`/`apply`/`proc_lib`/`timer`/`rpc` 的 MFA 参数调用边、`gen_server:call/cast(?MODULE)` → 自身 `handle_call`/`handle_cast` 链接、`-behaviour` 链接、基于 `-export` 的可见性） |
| Solidity | `.sol` | 完整支持（contract、library、interface、struct、enum、modifier、event、error、state variable、`import`/`using` 指令、`emit`/`revert` 调用） |
| Terraform / OpenTofu | `.tf`, `.tfvars`, `.tofu` | 完整支持（resource、data source、module、variable、output、provider、`locals`；`var.`/`local.`/`module.`/resource 引用，遵循 Terraform 的按目录作用域；跨边界桥接 module 调用 —— 输入连到子 module 的 variable、`module.M.out` 连到子 module 的 output、`source` 连到该 module 的文件；`.tfvars` 赋值连到它设置的 variable） |

## 实测的跨文件覆盖率

影响范围与爆炸半径查询的好坏，全看背后的依赖图。所以覆盖率是**测**出来的，不是**说**出来的。**公平覆盖率** = 在每种语言的真实基准仓库上，至少拥有*一个已解析的跨文件依赖*（import、call、reference，或通过框架约定路由到它）的"含符号源文件"占比。剩余的部分始终是真正的静态分析前沿（运行时动态分发、反射/DI 容器、框架约定入口、第三方 vendored 代码），绝不会通过对分母动手脚来掩盖。

| 语言 | 基准仓库 | 覆盖率 |
|---|---|---|
| TypeScript / JavaScript | 本仓库 | 95.8% |
| Python | psf/requests | 100% |
| Go | gin-gonic/gin | 96.6% |
| Rust | BurntSushi/ripgrep | 86.7% |
| Java | google/gson | 93.3% |
| C# | jbogard/MediatR | 85.2% |
| PHP | guzzle/guzzle | 100% |
| Ruby | sidekiq/sidekiq | 100% |
| C | redis/redis | 92.2% |
| C++ | google/leveldb | 94.8% |
| Objective-C | SDWebImage | 91.6% |
| Swift | Alamofire | 95.3% |
| Kotlin | square/okhttp | 96.2% |
| Scala | gatling/gatling | 91.2% |
| Dart | flutter/packages | 92.4% |
| Svelte / SvelteKit | sveltejs/realworld | 100% |
| Vue / Nuxt | nuxt/movies | 93.5% |
| Astro | xingwangzhe/stalux | 93.0% |
| Lua | nvim-telescope/telescope.nvim | 84.2% |
| Luau | dphfox/Fusion | 92.2% |
| Liquid | Shopify/dawn | 73.8% |
| Pascal / Delphi | PascalCoin | 77.4% |

框架路由也以同样方式验证 —— 每个框架选一个典型应用：Express 100%、FastAPI 98%、Flask 100%、NestJS 96.8%、Gin 96.5%、Axum 100%、Rocket 93.8%、Vapor 100%、Laravel 92%、Rails 89.6%、React Router 100% —— 而那些重度依赖约定/反射的框架，停在了它们诚实的静态分析上限：ASP.NET 83.9%、Spring 83.3%、Drupal 78.9%、Play 76.3%、Django 74.1%。SvelteKit、Vue/Nuxt、Astro 使用文件式路由，所以它们的 page/endpoint 覆盖率就是上表中的 Svelte/SvelteKit（100%）、Vue/Nuxt（93.5%）、Astro（93.0% —— 在两个验证仓库里每个 `src/pages/` 文件都映射到一个 route 节点）。

## 故障排查

**"CodeGraph not initialized"** —— 先在项目目录运行 `codegraph init`。

**索引很慢** —— 检查 `node_modules` 等大目录是否被排除。用 `--quiet` 减少输出开销。

**MCP 报 `database is locked`** —— 当前构建本不该出现：CodeGraph 自带 Node 运行时，使用 Node 内置的 `node:sqlite`，启用 WAL 模式，并发读永远不会阻塞写。如果仍然出现：

- **你装的是老版本（pre-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 服务器连不上** —— agent 自己启动该服务器，你不需要手动启动。确保项目已初始化并索引（`codegraph status`），且 MCP 配置里的路径正确。如果还是连不上，重跑 `codegraph install` 重写配置。

**`codegraph status`/`sync` 一切正常，但 MCP 工具调用报 `Transport closed`** —— 几乎都是 WSL2 且项目位于 Windows 盘（`/mnt/c` 或 `/mnt/d` 路径）的情况：CodeGraph 用来跨会话共享同一个后台服务器的本地 socket 在该文件系统上不可靠。CodeGraph 现在会退化为在会话内 in-process 服务，而不是掉线，但如果还遇到，可以在 MCP 服务器的环境里设 `CODEGRAPH_NO_DAEMON=1` 完全跳过共享服务器（每个会话各自一个进程）。把项目挪到 Linux 原生文件系统（比如 `~/` 之下而不是 `/mnt/`）即可恢复共享服务器。

**符号缺失** —— MCP 服务器在保存时自动同步（等几秒）。必要时手动跑 `codegraph sync`。检查文件语言是否受支持、是否位于 `.gitignore` 目录或默认排除目录（如 `node_modules`、`dist`）。

**Windows 与 WSL 共用一份 checkout** —— 不要让两边指向同一个 `.codegraph/`：后台服务器锁与 SQLite 索引与写入它们的 OS 绑定，且 SQLite 锁在 WSL2/Windows 文件系统边界上不可靠。给每边各自一份索引，让它们处于同一棵代码树：在其中一边把 `CODEGRAPH_DIR` 设成不同名字 —— 比如 Windows 上设 `CODEGRAPH_DIR=.codegraph-win`，WSL 保持默认的 `.codegraph`。CodeGraph 在索引和监视时会跳过任何同级 `.codegraph-*` 目录，所以两边互不干扰。

## Star History

<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 History Chart" 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>