CodeGraph

為 Claude Code、Cursor、Codex 和 OpenCode 注入語義代碼智能

成本降低約 35% · 工具調(diào)用減少約 70% · 100% 本地運(yùn)行

快速開始

npx @colbymchenry/codegraph

交互式安裝程序自動(dòng)配置你的 Agent——Claude Code、Cursor、Codex CLI、opencode

初始化項(xiàng)目

cd your-project codegraph init -i

為什么選擇 CodeGraph？

當(dāng) Claude Code 探索代碼庫時(shí)，它會(huì)啟動(dòng) Explore Agent，通過 grep、glob 和 Read 掃描文件——每次工具調(diào)用都會(huì)消耗 token。

CodeGraph 為這些 Agent 提供一個(gè)預(yù)先索引好的知識(shí)圖譜——包含符號(hào)關(guān)系、調(diào)用圖和代碼結(jié)構(gòu)。Agent 可以即時(shí)查詢圖譜，而無需掃描文件。

基準(zhǔn)測(cè)試結(jié)果

測(cè)試覆蓋 7 個(gè)涵蓋 7 種語言的真實(shí)開源代碼庫，對(duì)比一個(gè) Agent（Claude Code，無界面模式）在有和沒有 CodeGraph 的情況下回答同一個(gè)架構(gòu)問題的表現(xiàn)。每個(gè)單元格為每組 4 次運(yùn)行取中位數(shù)的節(jié)省幅度。

平均：成本降低 35% · token 減少 59% · 速度提升 49% · 工具調(diào)用減少 70%

| 代碼庫 | 語言 | 成本 | Token | 時(shí)間 | 工具調(diào)用 |

| VS Code | TypeScript · 約 10k 文件 | 成本降低 35% | 減少 73% | 速度提升 41% | 減少 72% |

| Excalidraw | TypeScript · 約 600 | 成本降低 47% | 減少 73% | 速度提升 60% | 減少 86% |

| Django | Python · 約 2.7k | 成本降低 34% | 減少 64% | 速度提升 59% | 減少 81% |

| Tokio | Rust · 約 700 | 成本降低 52% | 減少 81% | 速度提升 63% | 減少 89% |

| OkHttp | Java · 約 640 | 成本降低 17% | 減少 41% | 速度提升 36% | 減少 64% |

| Gin | Go · 約 150 | 成本降低 22% | 減少 23% | 速度提升 34% | 減少 19% |

| Alamofire | Swift · 約 100 | 成本降低 38% | 減少 59% | 速度提升 51% | 減少 77% |

收益隨代碼庫規(guī)模擴(kuò)大而增長(zhǎng)：在大型代碼庫中，Agent 僅需幾次調(diào)用即可從索引中得出答案，零文件讀取；而沒有 CodeGraph 時(shí)，Agent 會(huì)大量展開 grep/find/Read 操作（以及它所啟動(dòng)的子 Agent）。對(duì)于像 Gin（約 150 個(gè)文件）這樣的小型代碼庫，原生搜索本身已經(jīng)很廉價(jià)，因此收益差距會(huì)縮小。

完整基準(zhǔn)測(cè)試詳情

方法論。 每組測(cè)試為 claude -p（Claude Opus 4.7，Claude Code v2.1.145）以無界面模式運(yùn)行于代碼庫，配置為 --strict-mcp-config：WITH = 啟用 CodeGraph 的 MCP server，WITHOUT = 空 MCP 配置。兩組均可使用內(nèi)置的 Read/Grep/Bash。每個(gè)代碼庫使用相同問題，每組 4 次運(yùn)行，取中位數(shù)上報(bào)。成本 = 該次運(yùn)行的 total_cost_usd；Token = 處理的總 token 數(shù)（輸入含緩存 + 輸出）；時(shí)間 = 掛鐘時(shí)間；工具調(diào)用 = 所有工具調(diào)用次數(shù)，包含模型啟動(dòng)的子 Agent 內(nèi)部的調(diào)用。代碼庫在 --depth 1 克隆，并由提供服務(wù)的同一 CodeGraph 構(gòu)建版本進(jìn)行索引。

查詢問題：

| 代碼庫 | 查詢 |

| VS Code | "extension host 如何與主進(jìn)程通信？" |

| Excalidraw | "Excalidraw 如何渲染并更新畫布元素？" |

| Django | "Django 的 ORM 如何從 QuerySet 構(gòu)建并執(zhí)行查詢？" |

| Tokio | "Tokio 如何在運(yùn)行時(shí)調(diào)度和運(yùn)行異步任務(wù)？" |

| OkHttp | "OkHttp 如何通過攔截器鏈處理請(qǐng)求？" |

| Gin | "gin 如何通過中間件鏈路由請(qǐng)求？" |

| Alamofire | "Alamofire 如何構(gòu)建、發(fā)送并校驗(yàn)請(qǐng)求？" |

原始中位數(shù) — WITH → WITHOUT：

| 代碼庫 | 成本 | Token | 時(shí)間 | 工具調(diào)用 |

| VS Code | $0.42 → $0.64 | 393k → 1.4M | 1m 0s → 1m 43s | 7 → 23 |

| Excalidraw | $0.54 → $1.02 | 851k → 3.2M | 1m 17s → 3m 14s | 12 → 83 |

| Django | $0.41 → $0.62 | 499k → 1.4M | 1m 0s → 2m 25s | 9 → 48 |

| Tokio | $0.50 → $1.04 | 657k → 3.4M | 1m 5s → 2m 56s | 9 → 75 |

| OkHttp | $0.36 → $0.44 | 352k → 596k | 45s → 1m 11s | 5 → 14 |

| Gin | $0.36 → $0.46 | 431k → 562k | 47s → 1m 11s | 7 → 8 |

| Alamofire | $0.61 → $0.99 | 1.1M → 2.6M | 1m 19s → 2m 41s | 15 → 64 |

CodeGraph 為何勝出： 有索引可用時(shí)，Agent 可以直接作答——codegraph_context 繪制范圍全貌，再一次 codegraph_explore 獲取相關(guān)源碼——隨即停止，通常零文件讀取。沒有索引時(shí)，Agent（及其啟動(dòng)的 Explore 子 Agent）會(huì)將大部分預(yù)算消耗在發(fā)現(xiàn)階段（find/ls/grep），才能讀到正確的代碼。CodeGraph 只有被直接查詢時(shí)才有效，因此其指令會(huì)引導(dǎo) Agent 直接作答，而非將探索委托給讀文件的子 Agent——否則子 Agent 依然會(huì)讀取文件，CodeGraph 反而成了額外開銷。

核心特性

| | |

| 智能上下文構(gòu)建 | 一次工具調(diào)用即可返回入口點(diǎn)、相關(guān)符號(hào)和代碼片段——無需昂貴的探索 Agent |

| 全文搜索 | 基于 FTS5，在整個(gè)代碼庫中按名稱即時(shí)查找代碼 |

| 影響分析 | 在修改前追蹤任意符號(hào)的調(diào)用方、被調(diào)用方及完整影響半徑 |

| 始終保持最新 | 文件監(jiān)聽器使用原生 OS 事件（FSEvents/inotify/ReadDirectoryChangesW）并配合防抖自動(dòng)同步——圖譜隨代碼編寫實(shí)時(shí)更新，零配置 |

| 支持 19+ 種語言 | TypeScript、JavaScript、Python、Go、Rust、Java、C#、PHP、Ruby、C、C++、Swift、Kotlin、Dart、Svelte、Liquid、Pascal/Delphi |

| 框架感知路由 | 識(shí)別 Web 框架路由文件，并跨 13 個(gè)框架將 URL 模式鏈接到對(duì)應(yīng)的處理器 |

| 100% 本地運(yùn)行 | 數(shù)據(jù)不離開本機(jī)，無需 API 密鑰，無需外部服務(wù)，僅使用 SQLite 數(shù)據(jù)庫 |

框架感知路由

CodeGraph 檢測(cè) Web 框架路由文件，生成 route 節(jié)點(diǎn)，并通過 references 邊鏈接到對(duì)應(yīng)的處理器類或函數(shù)。查詢某個(gè)視圖/控制器的調(diào)用方時(shí)，現(xiàn)在可以同時(shí)顯示綁定它的 URL 模式。

| 框架 | 識(shí)別的寫法 |

| Django | path()、re_path()、url()、include() 位于 urls.py 中（CBV .as_view()、點(diǎn)分路徑） |

| Flask | @app.route('/path', methods=[...])、藍(lán)圖路由 |

| FastAPI | @app.get(...)、@router.post(...)，所有標(biāo)準(zhǔn)方法 |

| Express | app.get(...)、router.post(...) 含中間件鏈 |

| NestJS | @Controller + @Get/@Post/...、GraphQL @Resolver + @Query/@Mutation、@MessagePattern/@EventPattern、@SubscribeMessage |

| Laravel | Route::get()、Route::resource()、Controller@action、元組語法 |

| Rails | get '/x', to: 'users#index'、哈?；鸺?=> 語法 |

| Spring | @GetMapping、@PostMapping、方法上的 @RequestMapping |

| 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 | 路由組件節(jié)點(diǎn) |

快速上手

1. 運(yùn)行安裝程序

npx @colbymchenry/codegraph

安裝程序?qū)ⅲ?/p>

• 詢問要配置哪些 Agent——自動(dòng)檢測(cè)已安裝的 Agent，涵蓋：Claude Code、Cursor、Codex CLI、opencode

• 提示是否將 codegraph 安裝到 PATH（以便 Agent 啟動(dòng) MCP server）

• 詢問配置是應(yīng)用于所有項(xiàng)目還是僅當(dāng)前項(xiàng)目

• 為每個(gè)選定的 Agent 寫入 MCP server 配置及指令文件（例如 CLAUDE.md、.cursor/rules/codegraph.mdc、~/.codex/AGENTS.md）

• 當(dāng)目標(biāo)包含 Claude Code 時(shí)，配置自動(dòng)授權(quán)權(quán)限

• 初始化當(dāng)前項(xiàng)目（僅限本地安裝）

非交互式（腳本 / CI）：

codegraph install --yes # auto-detect agents, install global codegraph install --target=cursor,claude --yes # explicit target list codegraph install --target=auto --location=local # detected agents, project-local codegraph install --print-config codex # print snippet, no file writes

| 標(biāo)志 | 取值 | 默認(rèn)值 |

| --target | auto、all、none，或以逗號(hào)分隔（claude,cursor,...） | 交互提示 |

| --location | global、local | 交互提示 |

| --yes | （布爾值） | 每步交互提示 |

| --no-permissions | （布爾值）跳過 Claude 自動(dòng)授權(quán)列表 | 啟用權(quán)限管理 |

| --print-config | 輸出某個(gè) Agent 的配置片段后退出 | — |

2. 重啟你的 Agent

重啟你的 Agent（Claude Code / Cursor / Codex CLI / opencode）以加載 MCP server。

3. 初始化項(xiàng)目

cd your-project codegraph init -i

構(gòu)建項(xiàng)目級(jí)知識(shí)圖譜索引。同時(shí)配置任何項(xiàng)目本地的 Agent 界面（例如 Cursor 的 .cursor/rules/codegraph.mdc），使單一全局 codegraph install 在你打開的每個(gè)項(xiàng)目中均可生效——無需為每個(gè)項(xiàng)目重新運(yùn)行安裝程序。

就這些——只要存在 .codegraph/ 目錄，你的 Agent 就會(huì)自動(dòng)使用 CodeGraph 工具。

手動(dòng)配置（備選方案）

全局安裝：

npm install -g @colbymchenry/codegraph

添加到 ~/.claude.json：

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

添加到 ~/.claude/settings.json（可選，用于自動(dòng)授權(quán)）：

{ "permissions" : { "allow" : [ " mcp__codegraph__codegraph_search " , " mcp__codegraph__codegraph_context " , " mcp__codegraph__codegraph_callers " , " mcp__codegraph__codegraph_callees " , " mcp__codegraph__codegraph_impact " , " mcp__codegraph__codegraph_node " , " mcp__codegraph__codegraph_status " , " mcp__codegraph__codegraph_files " ] } }

全局指令參考

安裝程序會(huì)自動(dòng)將以下指令添加到 ~/.claude/CLAUDE.md：

## CodeGraph CodeGraph builds a semantic knowledge graph of codebases for faster, smarter code exploration. ### If ` .codegraph/ ` exists in the project ** NEVER call ` codegraph_explore ` or ` codegraph_context ` directly in the main session. ** These tools return large amounts of source code that fills up main session context. Instead, ALWAYS spawn an Explore agent for any exploration question (e.g., "how does X work?", "explain the Y system", "where is Z implemented?"). ** When spawning Explore agents ** , include this instruction in the prompt: > This project has CodeGraph initialized (.codegraph/ exists). Use ` codegraph_explore ` as your PRIMARY tool — it returns full source code sections from all relevant files in one call. > > ** Rules: ** > 1 . Follow the explore call budget in the ` codegraph_explore ` tool description — it scales automatically based on project size. > 2 . Do NOT re-read files that codegraph_explore already returned source code for. The source sections are complete and authoritative. > 3 . Only fall back to grep/glob/read for files listed under "Additional relevant files" if you need more detail, or if codegraph returned no results. ** The main session may only use these lightweight tools directly ** (for targeted lookups before making edits, not for exploration): | Tool | Use For | | ------ | --------- | | ` codegraph_search ` | Find symbols by name | | ` codegraph_callers ` / ` codegraph_callees ` | Trace call flow | | ` codegraph_impact ` | Check what's affected before editing | | ` codegraph_node ` | Get a single symbol's details | ### If ` .codegraph/ ` does NOT exist At the start of a session, ask the user if they'd like to initialize CodeGraph: "I notice this project doesn't have CodeGraph initialized. Would you like me to run ` codegraph init -i ` to build a code knowledge graph?"

工作原理

┌─────────────────────────────────────────────────────────────────┐ │ Claude Code │ │ │ │ "Implement user authentication" │ │ │ │ │ ▼ │ │ ┌─────────────────┐ ┌─────────────────┐ │ │ │ Explore Agent │ ──── │ Explore Agent │ │ │ └────────┬────────┘ └────────┬────────┘ │ │ │ │ │ └───────────┼────────────────────────┼─────────────────────────────┘ │ │ ▼ ▼ ┌───────────────────────────────────────────────────────────────────┐ │ CodeGraph MCP Server │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ Search │ │ Callers │ │ Context │ │ │ │ "auth" │ │ "login()" │ │ for task │ │ │ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │ │ │ │ │ │ │ └────────────────┼────────────────┘ │ │ ▼ │ │ ┌───────────────────────┐ │ │ │ SQLite Graph DB │ │ │ │ ? 387 symbols │ │ │ │ ? 1,204 edges │ │ │ │ ? Instant lookups │ │ │ └───────────────────────┘ │ └───────────────────────────────────────────────────────────────────┘

• 提取 — tree-sitter 將源碼解析為 AST。語言專屬查詢從中提取節(jié)點(diǎn)（函數(shù)、類、方法）和邊（調(diào)用、導(dǎo)入、繼承、實(shí)現(xiàn)）。

• 存儲(chǔ) — 所有數(shù)據(jù)寫入本地 SQLite 數(shù)據(jù)庫（.codegraph/codegraph.db），并啟用 FTS5 全文搜索。

• 解析 — 提取完成后進(jìn)行引用解析：函數(shù)調(diào)用→定義，導(dǎo)入→源文件，類繼承以及框架專屬模式。

• 自動(dòng)同步 — MCP server 使用原生 OS 文件事件監(jiān)聽項(xiàng)目變化。變更經(jīng)過防抖處理（2 秒靜默窗口），僅過濾源文件，并進(jìn)行增量同步。圖譜隨代碼編寫實(shí)時(shí)保持最新——無需任何配置。

CLI 參考

codegraph # Run interactive installer codegraph install # Run installer (explicit) codegraph init [path] # Initialize in a project (--index to also index) codegraph uninit [path] # Remove CodeGraph from a project (--force to skip prompt) codegraph index [path] # Full index (--force to re-index, --quiet for less output) codegraph sync [path] # Incremental update codegraph status [path] # Show statistics codegraph query # Search symbols (--kind, --limit, --json) codegraph files [path] # Show file structure (--format, --filter, --max-depth, --json) codegraph context # Build context for AI (--format, --max-nodes) codegraph affected [files...] # Find test files affected by changes (see below) codegraph serve --mcp # Start MCP server

codegraph affected

傳遞依賴地追蹤導(dǎo)入依賴關(guān)系，找出受已變更源文件影響的測(cè)試文件。

codegraph affected src/utils.ts src/api.ts # Pass files as arguments git diff --name-only | codegraph affected --stdin # Pipe from git diff codegraph affected src/auth.ts --filter " e2e/* " # Custom test file pattern

| 選項(xiàng) | 說明 | 默認(rèn)值 |

| --stdin | 從 stdin 讀取文件列表 | false |

| -d, --depth | 最大依賴遍歷深度 | 5 |

| -f, --filter | 自定義 glob 用于識(shí)別測(cè)試文件 | 自動(dòng)檢測(cè) |

| -j, --json | 以 JSON 格式輸出 | false |

| -q, --quiet | 僅輸出文件路徑 | false |

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

MCP 工具

以 MCP server 模式運(yùn)行時(shí)，CodeGraph 向 Claude Code 暴露以下工具：

| 工具 | 用途 |

| codegraph_search | 在代碼庫中按名稱查找符號(hào) |

| codegraph_context | 為某項(xiàng)任務(wù)構(gòu)建相關(guān)代碼上下文 |

| codegraph_callers | 查找調(diào)用某函數(shù)的位置 |

| codegraph_callees | 查找某函數(shù)調(diào)用了哪些內(nèi)容 |

| codegraph_impact | 分析修改某符號(hào)會(huì)影響哪些代碼 |

| codegraph_node | 獲取特定符號(hào)的詳細(xì)信息（可選擇包含源代碼） |

| codegraph_files | 獲取已索引的文件結(jié)構(gòu)（比文件系統(tǒng)掃描更快） |

| codegraph_status | 檢查索引健康狀態(tài)與統(tǒng)計(jì)信息 |

Library Usage

import CodeGraph from '@colbymchenry/codegraph' ; const cg = await CodeGraph . init ( '/path/to/project' ) ; // Or: 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 ( ) ; // auto-sync on file changes cg . unwatch ( ) ; // stop watching cg . close ( ) ;

Configuration

.codegraph/config.json 文件用于控制索引行為：

{ "version" : 1 , "languages" : [ " typescript " , " javascript " ], "exclude" : [ " node_modules/** " , " dist/** " , " build/** " , " *.min.js " ], "frameworks" : [], "maxFileSize" : 1048576 , "extractDocstrings" : true , "trackCallSites" : true }

| Option | Description | Default |

| languages | 需要索引的語言（為空則自動(dòng)檢測(cè)） | [] |

| exclude | 要忽略的 Glob 匹配模式 | ["node_modules/**", ...] |

| frameworks | 框架提示，用于改善解析效果 | [] |

| maxFileSize | 跳過超過此大小的文件（字節(jié)） | 1048576（1MB） |

| extractDocstrings | 從代碼中提取文檔字符串 | true |

| trackCallSites | 追蹤調(diào)用點(diǎn)位置 | true |

Supported Languages

| Language | Extension | Status |

| 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 | 完整支持 |

| Swift | .swift | 完整支持 |

| Kotlin | .kt、.kts | 完整支持 |

| Scala | .scala、.sc | 完整支持（類、trait、方法、類型別名、Scala 3 枚舉） |

| Dart | .dart | 完整支持 |

| Svelte | .svelte | 完整支持（script 提取、Svelte 5 runes、SvelteKit 路由） |

| Vue | .vue | 完整支持（script + script-setup 提取、Nuxt 頁面/API/中間件路由） |

| Liquid | .liquid | 完整支持 |

| Pascal / Delphi | .pas、.dpr、.dpk、.lpr | 完整支持（類、記錄、接口、枚舉、DFM/FMX 表單文件） |

Troubleshooting

"CodeGraph not initialized" — 請(qǐng)先在項(xiàng)目目錄中運(yùn)行 codegraph init。

索引速度慢 — 檢查 node_modules 及其他大型目錄是否已被排除。使用 --quiet 可降低輸出開銷。

索引速度慢 / MCP database is locked / WASM 回退已激活 — codegraph 附帶了一個(gè) WASM SQLite 回退方案，適用于 better-sqlite3（一個(gè)原生模塊，聲明為 optionalDependencies）無法安裝的環(huán)境。該回退方案比原生后端慢 5-10 倍，并使用一種允許寫操作阻塞讀操作的日志模式，因此在索引運(yùn)行期間，MCP 查詢也可能遭遇 database is locked。運(yùn)行 codegraph status 并查看 Backend: 行：

• Backend: native — 當(dāng)前使用的是快速路徑，無需任何操作。

• Backend: wasm — 當(dāng)前使用的是慢速回退。常見原因：缺少 C 構(gòu)建工具、當(dāng)前 Node 版本沒有可用的預(yù)構(gòu)建二進(jìn)制文件，或安裝后 Node 版本發(fā)生了變更。修復(fù)方法：# macOS xcode-select --install # installs the C compiler # Linux (Debian / Ubuntu) sudo apt install build-essential python3 make # Linux (RHEL / Fedora) sudo yum groupinstall " Development Tools " # Then rebuild on any platform: npm rebuild better-sqlite3 # Or force-include as a hard dep: npm install better-sqlite3 --save 修復(fù)完成后，codegraph status 應(yīng)顯示 Backend: native。

MCP 服務(wù)器無法連接 — 請(qǐng)確保項(xiàng)目已完成初始化/索引，驗(yàn)證 MCP 配置中的路徑是否正確，并檢查 codegraph serve --mcp 能否在命令行中正常運(yùn)行。

符號(hào)缺失 — MCP 服務(wù)器會(huì)在保存時(shí)自動(dòng)同步（請(qǐng)等待幾秒鐘）。如有需要，可手動(dòng)運(yùn)行 codegraph sync。請(qǐng)檢查該文件的語言是否受支持，以及是否被配置規(guī)則排除在外。

Star History

License

MIT

專為 AI 編程 Agent 打造 — Claude Code、Cursor、Codex CLI 以及 opencode

報(bào)告 Bug · 請(qǐng)求新功能