TL;DR：CodeGraph 把整個 codebase 預先建成一張「程式碼知識圖譜」（symbol 節點 + call 邊），讓 Claude Code、Codex、Cursor 這類 AI agent 不用一個一個檔案爬，一次 codegraph_explore 就拿到相關 source、call path 跟改動波及範圍。官方在 7 個真實開源專案的實測：VS Code 少 81% tool call、少 64% token，Alamofire 便宜 40%、快 33%。100% 本機跑、MIT、支援 23 種語言、8 個 agent。
我自己用 Claude Code 啃大型 codebase 時，最有感的浪費不是模型不夠聰明，是它得先「找路」——grep 一輪、Read 三五個檔、再 grep 一輪，光定位「這個函式被誰呼叫」就燒掉一堆 token 跟 tool call，真正改 code 前的探勘成本高得離譜。CodeGraph 就是衝著這個痛點來的：與其讓 agent 拿手電筒在黑暗檔案堆裡一個一個翻，不如先給它一張畫好的地圖。
這篇把 CodeGraph 是什麼、怎麼裝、實測數字、跟現有作法的差別、以及我接的時候要注意的點寫一遍。
📌 目錄
- CodeGraph 是什麼？解決什麼問題
- 為什麼 AI agent 爬檔案這麼貴
- CodeGraph 怎麼運作：tree-sitter + SQLite + file watcher
- 如何安裝 CodeGraph（含前置與驗證）
- 核心指令：init、explore、affected
- 實測數字：少 81% tool call 是怎麼來的
- CodeGraph vs grep vs 傳統 LSP 比較
- 設定檔 codegraph.json：排除與自訂副檔名
- 我接的時候踩到的坑 / 要注意的點
- ❓ 常見問題
- 🔗 延伸資源
🧠 CodeGraph 是什麼？解決什麼問題
CodeGraph 是一個本機優先（local-first）的程式碼知識圖譜工具，把任何 codebase 變成可查詢的圖：每一個 symbol（函式、類別、變數）是一個節點，每一條呼叫關係（誰呼叫誰）是一條邊。AI coding agent 透過 MCP（Model Context Protocol）直接查這張圖，而不是讀原始檔案。
關鍵是「預先索引」這四個字。傳統上 agent 要回答「processOrder 這個函式改了會影響誰」，得即時讀檔、即時推理。CodeGraph 在你 init 的時候就把整張圖建好存進本機 SQLite，agent 要什麼直接查，等於把探勘成本從「每次對話即時付」搬到「建一次圖一勞永逸」。
它強調三件事：fewer tokens（更少 token）、fewer tool calls（更少工具呼叫）、100% local（完全本機，不上雲）。授權是 MIT。
⚡ 為什麼 AI agent 爬檔案這麼貴
先講清楚這個成本，後面數字才有感。
當你叫 Claude Code「幫我看 auth 模組怎麼接到 user service」，它的標準動作是：
grep 關鍵字找候選檔Read 幾個檔把內容讀進 contextgrep 一輪Read 幾個被呼叫的檔每一次 Read 都把整檔（或一大段）塞進 context window，每一次 grep/Read 都是一次 tool call。一個中型 codebase 光「搞懂某個功能怎麼串」就可能十幾次工具呼叫、好幾萬 token。而且這些檔案讀進來大半是雜訊——agent 真正需要的只是「相關的那幾個 symbol + 它們的呼叫鏈」。
CodeGraph 的賣點就是把這整段壓縮成一次查詢：給你相關 source、給你 call path、給你 blast radius（改動波及範圍），其他不相關的檔連碰都不碰。
🔧 CodeGraph 怎麼運作
CodeGraph 是三層架構，每一層都用成熟的東西，沒有黑魔法：
| 層 | 用什麼 | 做什麼 |
|---|---|---|
| 解析層 | tree-sitter | 跨語言增量解析，從真實 AST 抽出 symbol 與 call edge（不是猜的） |
| 儲存層 | SQLite + FTS5 | 把 symbol、邊存成圖，FTS5 全文索引讓查詢快 |
| 同步層 | 原生 OS file watcher | FSEvents（macOS）/ inotify（Linux）/ ReadDirectoryChangesW（Windows），檔案一改就 debounced 自動更新圖 |
grep 只能比對字串，分不清 processOrder 是函式定義、呼叫、還是註解裡的字；tree-sitter 知道它是什麼、在哪個 scope、被誰呼叫。這就是 CodeGraph 能給出準確 call path 的根本原因。
init 完成後，auto-sync 預設開啟，CodeGraph 在背景盯著你的專案，每次存檔就增量更新圖——所以你不用每次手動 re-index。
📥 如何安裝 CodeGraph
CodeGraph 的安裝刻意做到「不挑環境」——bundled installer 自帶 runtime，不需要先裝 Node.js。
Prereq 表
| 依賴 | 最低版本 | 驗證 | 備註 |
|---|---|---|---|
| 作業系統 | macOS / Linux / Windows | uname -s | 三平台都支援 |
| Node（僅 npm 安裝法需要） | 任意版本 | node -v | bundled installer 不需要 |
| Node（要當 library 嵌入時） | 22.5+ | node -v | 一般 CLI 使用者用不到 |
一鍵安裝指令
# macOS / Linux — 官方 installer（自帶 runtime，免裝 Node）
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
# 任意 OS，已有 Node 想走 npm
npm i -g @colbymchenry/codegraph
接到你的 AI agent
裝完跑這行，CodeGraph 會自動偵測你機器上裝了哪些支援的 agent，並幫它們設好 MCP server：
codegraph install它對外只暴露一個 MCP 工具：codegraph_explore。agent 端不用你手動編 JSON config，這步幫你接好。
驗證安裝成功
codegraph status看到專案的 symbol 數、檔案數、圖譜統計，就代表圖建起來、CodeGraph 正常運作。第一次在新專案要先 init 才有東西可 status（見下節）。
⭐ 核心指令
CodeGraph 的 CLI 很精簡，記住這幾個就夠用：
| 指令 | 作用 |
|---|---|
codegraph install | 把 CodeGraph 接到本機的 AI agent（設定 MCP） |
codegraph init [path] | 初始化專案、一次建好整張圖（建立 .codegraph/） |
codegraph sync [path] | 手動增量更新（auto-sync 開著通常用不到） |
codegraph status [path] | 顯示圖譜統計 |
codegraph query | 依名稱搜尋 symbol |
codegraph explore | 一次拿到相關 symbol 的 source + call path |
codegraph affected [files...] | 找出某些檔案改動會波及的測試檔 |
我實際下的指令
進到專案根目錄，三步走完：
# 1. 建圖（auto-sync 預設開，之後存檔自動更新）
codegraph init
# 2. 接 AI agent
codegraph install
# 3. 確認圖建好
codegraph status
之後在 Claude Code 裡，agent 就會自己呼叫 codegraph_explore 去查圖，不用你下指令。想自己手動探勘也可以：
# 一次拿到 processOrder 相關的 source 跟呼叫鏈
codegraph explore "processOrder payment flow"
# 改了這兩個檔，哪些測試會被影響？
codegraph affected src/auth/login.ts src/user/service.ts
affected 對「改 code 前先知道要跑哪些測試」特別實用，不用整套 test suite 重跑。
💰 實測數字
官方在 7 個真實開源 codebase 上跑 benchmark（取 4 次中位數），數字逐個列在 README。我挑幾個有代表性的：
| Codebase | tool call 減少 | token 減少 | 速度 | 成本 |
|---|---|---|---|---|
| VS Code | 81% | 64% | 快 11% | 便宜 18% |
| Django | 77% | 60% | 快 13% | 便宜 8% |
| Alamofire | 58% | 64% | 快 33% | 便宜 40% |
數字差異要怎麼看？token / tool call 的降幅最穩定（普遍 60%↑、80%↑），因為這直接對應「不用爬檔」這件事。成本降幅波動較大（8%~40%），因為它跟模型計價、那次任務的輸出量都有關。換句話說，CodeGraph 最確定能省的是「探勘階段的 token 與工具呼叫」，省到的錢則看你的用量結構。
對我這種把 Claude Code 接公司大型 repo 的場景，「file read 砍到接近零」這句最戳——大 codebase 的痛從來不是改 code，是 agent 為了搞懂上下文先把半個專案讀進 context。
⚖️ CodeGraph vs grep vs 傳統 LSP 比較
知識圖譜不是新概念，IDE 的 LSP（Language Server Protocol）早就在做「找定義、找 reference」。差別在「為誰服務」。
| 維度 | grep / Read | 傳統 LSP（IDE） | CodeGraph |
|---|---|---|---|
| 比對方式 | 字串比對 | 真實 AST | 真實 AST（tree-sitter） |
| 服務對象 | 人 + agent 硬爬 | 給 IDE 的人類使用者 | 專為 AI agent 設計 |
| 一次拿到 call path | ✗ 要多輪 | △ 要逐步點 | ✓ 一次 explore |
| blast radius（波及範圍） | ✗ | △ find references | ✓ affected 直給 |
| token 成本 | 高（整檔讀入） | 不適用 | 低（只回相關 symbol） |
| 接 AI agent | 需手刻 | 不直接 | ✓ MCP 原生 |
| 本機 / 隱私 | 本機 | 本機 | ✓ 100% 本機 |
codegraph_explore）。兩者不衝突，但要餵給 AI 的話 CodeGraph 的介面對得多。
🎨 設定檔 codegraph.json
CodeGraph 預設 zero-config，但大型專案常需要微調。它只認三個 key，放在專案根的 codegraph.json：
{
"exclude": ["static/", "/vendor/"],
"extensions": {
".dota_lua": "lua",
".tpl": "php"
},
"includeIgnored": ["packages/", "services/"]
}| key | 作用 |
|---|---|
exclude | gitignore 式 pattern，把不想索引的檔（commit 進來的相依、靜態檔）排掉，讓圖更乾淨 |
extensions | 把非標準副檔名對應到支援的語言（例 .tpl 當 PHP 解） |
includeIgnored | super-repo 場景：子 repo 被 gitignore 但想一起索引時，重新納入 |
node_modules、vendor、dist、.gitignore 命中的檔、以及超過 1 MB 的檔。改完設定要 re-index 才生效。
📝 踩坑與要注意的點
接的時候我整理幾個值得先知道的坑：
踩坑一：init 要在專案根目錄跑
codegraph init 會在當前目錄建 .codegraph/（裡面是 codegraph.db 這個 SQLite 檔）。跑錯目錄會在子資料夾建一個只含部分檔案的圖。建議把 .codegraph/ 加進 .gitignore——它是本機快取，不該進版控。
踩坑二：改了 codegraph.json 一定要 re-index
auto-sync 只追「檔案內容變更」，不會自動套用設定檔的變更。你新增 exclude 後若沒重新索引，被排除的檔還在圖裡。改設定後手動跑一次 re-index。
benchmark 是中位數，不是保證值
官方數字是 4 次中位數、特定任務。你自己專案的降幅取決於 codebase 大小、語言、任務型態。值得跑前後對照自己驗，而不是直接拿 81% 當 KPI。
支援 23 種語言，但深度看語言
CodeGraph 列出 23 種語言（TypeScript、JavaScript、Python、Go、Rust、Java、C#、PHP、Ruby、C、C++、Swift、Kotlin、Scala、Dart、Lua、R、Svelte、Vue、Astro 等）。tree-sitter 各語言 grammar 成熟度不同，主流語言（TS/Py/Go）的 call edge 準確度通常比小眾語言好，冷門語言建議實測過再信任它的 blast radius。
❓ 常見問題
Q1. CodeGraph 會把我的程式碼上傳到雲端嗎？
不會。CodeGraph 強調 100% local，圖建在本機 .codegraph/codegraph.db（SQLite），解析與查詢都在你機器上跑，不外送。這對公司內網、有保密需求的 codebase 是關鍵。
Q2. 一定要裝 Node.js 嗎？
用官方 install.sh / install.ps1 不用——它自帶 runtime。只有走 npm i -g 安裝、或要把 CodeGraph 當 library 嵌入（需 Node 22.5+）才需要 Node。
Q3. 它跟 Claude Code 內建的搜尋有什麼不一樣？
Claude Code 預設靠 grep + Read 即時爬檔，每次都付探勘成本。CodeGraph 預先把整張呼叫圖建好，agent 透過 MCP 一次查就拿到 call path 與波及範圍，省掉反覆讀檔——官方實測 file read 接近零、tool call 大幅下降。
Q4. 支援哪些 AI agent？
8 個：Claude Code、Cursor、Codex CLI、opencode、Hermes Agent、Gemini CLI、Antigravity IDE、Kiro。codegraph install 會自動偵測已安裝的並設好 MCP。
Q5. 大專案改一個檔，圖會整個重建嗎？
不會。同步是增量的，file watcher 偵測變更後只更新受影響的部分（debounced），所以一般存檔不會卡。
🔗 延伸資源
- CodeGraph GitHub repo（MIT，含完整 README 與 benchmark）
- CodeGraph 官方文件站
- CodeGraph Configuration 設定文件
- 作者 Colby McHenry 的 Medium 心得文
- 站內延伸：如果你正在把 AI agent 接進工作流，可以一起看我寫過的其他 AI 工具實作紀錄。