CodeGraph 是一個給 AI 編程工具使用的本地程式碼知識圖譜。它會提前給專案建立索引，把符號關係、呼叫圖、程式碼結構、路由關係等資訊整理成可查詢的圖，讓 Claude Code、Codex CLI、Cursor、OpenCode、Hermes Agent 這類工具不用每次都靠 grep、glob、Read 和子代理到處翻檔案。
它解決的是一個很實際的問題：AI Agent 看大型程式碼庫時，很多成本不是花在真正修改程式碼上，而是花在「找程式碼在哪裡」。如果每次都重新搜尋、讀取、篩選，token、時間和工具呼叫都會被消耗掉。CodeGraph 的思路是先把程式碼庫變成一張本地地圖，讓 Agent 先問地圖，再決定要不要讀具體檔案。
它主要解決什麼痛點
AI 編程工具在小專案裡通常還好，檔案少，搜尋快，讀一遍也不貴。但專案一大，常見問題就會出現：
- Agent 為了理解一個模組，反覆呼叫 grep、find、ls、Read。
- 探索子代理讀了很多無關檔案，主任務上下文卻沒有變清楚。
- 問一個架構問題時，token 大量花在定位檔案上。
- 改一個函式前，不知道誰在呼叫它、它又呼叫了誰。
- Web 專案裡，URL 路由和實際處理函式之間的關係不夠直觀。
CodeGraph 試圖把這些「先找路」的工作前置。專案索引建好後，Agent 可以直接查詢相關符號、呼叫方、被呼叫方、影響範圍和程式碼片段。
安裝方式
專案提供跨平台安裝腳本，不要求使用者自己準備 Node.js：
|
|
Windows PowerShell 可以使用：
|
|
如果已經有 Node 環境，也可以直接用 npm：
|
|
或者全域安裝：
|
|
安裝器會自動偵測並配置已安裝的 Agent，例如 Claude Code、Cursor、Codex CLI、opencode 和 Hermes Agent。它會寫入對應的 MCP server 配置和指令檔案，讓這些工具知道什麼時候呼叫 CodeGraph。
初始化專案
安裝完成後，需要在目標專案裡建立索引：
|
|
這個命令會產生專案級知識圖譜索引。README 中提到，只要專案裡存在 .codegraph/ 目錄，Agent 就可以自動使用 CodeGraph 工具。
如果不想繼續使用，也可以卸載全域配置：
|
|
它會移除安裝器寫入的 MCP server 配置、指令和權限。專案中的 .codegraph/ 索引不會被自動刪除，如果要移除專案索引，需要使用 codegraph uninit。
為什麼它對 Agent 有用
Claude Code、Codex CLI、Cursor 這類工具在理解程式碼庫時，常常會先做探索：找檔案、讀入口、查引用、再追呼叫鏈。這個過程對人來說像「翻專案」，對模型來說就是一串工具呼叫和上下文消耗。
CodeGraph 把這一步變成索引查詢。Agent 可以先用 codegraph_context 找到相關入口、符號和片段，再用 codegraph_explore 或其他工具讀取必要內容。這樣做的好處是：
- 少讀無關檔案。
- 少呼叫搜尋工具。
- 更快找到真正相關的程式碼。
- 改動前更容易看清影響範圍。
- 大型倉庫裡的架構問題更容易回答。
專案 README 給出的基準測試顯示，在 7 個真實開源程式碼庫上，對比啟用 CodeGraph 和不啟用 CodeGraph，平均結果是成本更低、token 更少、速度更快、工具呼叫更少。具體數字會受專案規模、語言、問題類型和 Agent 使用方式影響，但方向很清楚：越大的倉庫，預索引的價值越明顯。
核心能力
1. 智慧上下文構建
一個工具呼叫可以返回入口點、相關符號和程式碼片段，減少 Agent 先派一堆探索任務再慢慢篩選的情況。對架構理解、模組定位、功能入口分析很有用。
2. 全文搜尋
CodeGraph 使用 FTS5 做全文搜尋，可以在整個程式碼庫裡快速按名稱和文字查找程式碼。這不是替代所有 grep 場景，而是讓 Agent 有一個更結構化的第一站。
3. 影響分析
在改函式、類別、方法或路由前，可以查詢 callers、callees 和影響半徑。對重構、修 bug、刪除舊程式碼尤其有用，因為最怕的就是只改了當前檔案，卻漏掉上游或下游呼叫。
4. 自動保持新鮮
README 中提到，CodeGraph 使用原生檔案系統事件，例如 FSEvents、inotify、ReadDirectoryChangesW，並帶有 debounce auto-sync。意思是索引會隨著本地程式碼變化自動更新，不需要每改一個檔案都手動重建。
5. 多語言支援
專案列出的支援範圍超過 19 種語言，包括 TypeScript、JavaScript、Python、Go、Rust、Java、C#、PHP、Ruby、C、C++、Swift、Kotlin、Dart、Lua、Luau、Svelte、Liquid、Pascal / Delphi 等。
這讓它更適合多語言倉庫和全棧專案，而不是只服務某一種語言。
6. Web 路由感知
CodeGraph 還會識別多種 Web 框架裡的路由檔案和路由宣告，把 URL pattern 和處理函式連接起來。README 中提到的框架包括 Django、Flask、FastAPI、Express、NestJS、Laravel、Rails、Spring、Gin、Axum、ASP.NET、Vapor、React Router、SvelteKit 等。
這點很實用。很多 Web 專案的真實入口不是某個明顯的 main 函式，而是路由、controller、handler、view 或 resolver。Agent 如果能先知道 URL 到處理函式的關係，理解業務流程會快很多。
本地優先的設計
CodeGraph 強調 100% local。它不需要 API key，不依賴外部服務，索引資料保存在本地 SQLite 資料庫裡。
對企業專案、私有倉庫或敏感程式碼來說，這個設計很重要。AI 工具接入程式碼庫時，大家最擔心的往往不是「能不能查到程式碼」，而是「程式碼結構和索引會不會被發出去」。CodeGraph 的定位是本地構建、本地查詢、本地服務 Agent。
當然，本地也意味著要考慮磁碟空間、索引時間、檔案監聽和專案規模。如果倉庫特別大，第一次初始化和後續同步仍然需要資源。
適合哪些場景
CodeGraph 更適合這些場景：
- 大型程式碼庫，經常需要問架構和呼叫鏈問題。
- 使用 Claude Code、Codex CLI、Cursor 等 Agent 做程式碼理解和修改。
- 希望減少 Agent 到處讀檔案、亂搜、反覆探索。
- 需要在改動前分析影響範圍。
- Web 專案路由複雜，需要快速從 URL 找到處理函式。
- 團隊希望給 AI Agent 一個更穩定的本地專案索引。
如果只是幾十個檔案的小專案，普通搜尋已經夠快，CodeGraph 的優勢可能不明顯。它最有價值的地方，是中大型程式碼庫和經常讓 Agent 做探索的場景。
使用時要注意什麼
第一，CodeGraph 不是替代程式碼審查和測試的工具。它能幫助 Agent 更快找到相關程式碼，但不能保證 Agent 的修改一定正確。
第二，索引品質會影響使用效果。專案結構複雜、生成程式碼很多、語言混雜或 build 產物沒有排除時，索引可能會變得臃腫。使用前最好確認 .gitignore、專案目錄和索引範圍是否合理。
第三，MCP 配置和 Agent 指令很關鍵。README 裡也提醒，CodeGraph 只有在被正確查詢時才有幫助。如果 Agent 仍然繞開它去大量讀檔案，預索引就會變成額外開銷。
第四，雖然它是本地工具，也要注意權限。安裝器會寫入 Agent 配置和權限列表，團隊環境中最好統一審查這些配置。
小結
CodeGraph 的價值可以簡單理解為：給 AI Agent 一張本地程式碼地圖。它不是讓模型更聰明，而是讓模型少迷路。
當 Claude Code、Codex CLI、Cursor 這類工具面對大型倉庫時，最耗費上下文的往往是探索過程。CodeGraph 用預索引的符號關係、呼叫圖、路由圖和全文搜尋，把「找程式碼」這一步提前做好，讓 Agent 把更多預算花在理解和修改上。
如果你已經在真實專案裡使用 AI 編程工具，並且經常遇到「它讀了一堆檔案還是沒找到重點」的情況，CodeGraph 值得試一下。它代表了 AI 編程工具的一個重要方向：不只是換更強的模型，也要給模型更好的本地程式碼上下文。
參考資料：