自動同步機制

為什麼需要三層

你的 agent（Claude Code、Cursor、Codex、opencode…）啟動 codegraph serve --mcp 時，三層機制讓索引與你的程式碼保持同步——並確保在「編輯完 → 下一次同步」的短暫窗口內，agent 不會拿到安靜的錯誤答案。

① File watcher with debounced auto-sync

原生 FSEvents / inotify / ReadDirectoryChangesW watcher 捕捉每個原始檔的 create / modify / delete，在 debounce 窗口（預設 2000ms，可用 CODEGRAPH_WATCH_DEBOUNCE_MS 調，範圍 [100ms, 60s]）後觸發 re-index。一陣編輯連發會被折疊成一次同步。

② Per-file staleness banner

在短暫的 debounce 窗口內，codegraph_explore 回應裡若引用了尚未入索引的檔案，會前置一個 ⚠️ 橫幅，指名該檔案並叫 agent 直接 Read 它。沒被回應引用的 pending 檔則以小 footer 呈現。無論哪種，agent 都拿到明確訊號——已用 Claude Code 驗證：agent 會先說「Reading the file directly for the live content」再開檔。

③ Connect-time catch-up

MCP server（重新）連線時，codegraph 會在回答第一個問題前，先對 working tree 做一次快速 (size, mtime) + content-hash 對帳——所以「沒有 MCP server 在跑期間」的編輯（終端 git pull、別的 editor 的編輯、前一個 agent session 退出）都會在下次 session 的第一次工具呼叫時被吸收。

流程示意

agent writes src/Widget.ts
  → watcher fires (<100ms)
  → debounce (default 2s)
  → sync; Widget.ts is in the index
  → next agent query sees it

任何時候可用 codegraph status（CLI）驗證；有 pending 會看到 ### Pending sync: 區段，列出檔案與編輯年齡。

什麼時候需要手動 codegraph sync

很少。手動 sync 有意義的時機：watcher 被停用（sandbox 環境，或 CODEGRAPH_NO_DAEMON=1），或你在 agent session 外寫腳本對索引做 pre-flight sync。

本站實測

$ codegraph sync
┌  Syncing CodeGraph
Scanning files...
Parsing code...
Resolving refs...
◆  Synced 3 changed files
●  Added: 3 — 0 nodes in 169ms
└  Done

上級 repo 對 sync 的實測目標：中型 repo 單檔編輯 ~0.3s，27,000 檔 Swift compiler repo ~0.4s；「永遠不需要手動 re-run」的承諾來自於只同步變動部分。