Agent Flow：把 Claude Code 與 Codex 的執行過程畫成節點圖
Real-time visualization of Claude Code agent orchestration — see your agents think, branch, and coordinate as they work.
秒懂
- 它是什麼？
- 這是一個把 agent 執行過程視覺化的工具，支援 Claude Code 與 Codex 兩套 runtime，可透過 VS Code 擴充套件、npx 指令或自行建置三種方式啟動。它的價值在於把黑箱變成可追蹤的事件流，代價是你得接受它對 Claude Code hooks 的依賴。
- 適合誰用？
- 如果你正在用 Claude Code 或 Codex 處理多步驟任務，而且經常需要回頭追查某一次執行到底呼叫了哪些工具、在哪裡分支，Agent Flow 值得先跑一次 npx agent-flow-app 觀察自己的 session 長什麼樣子。若你只是偶爾用 Claude Code 寫幾個檔案，或你無法接受擴充套件自動改寫 Claude Code hooks 設定，那它帶來的資訊量不足以抵銷安裝成本。
- 可以商用嗎？
- 可以。Apache-2.0 是寬鬆授權：你可以使用、修改並販售以它為基礎的軟體，只需保留著作權與授權聲明。
- 還在維護嗎？
- 有在維護。儲存庫最近一次提交在 66 天前。
- 用什麼語言寫的？
- 主要是 TypeScript（依據 GitHub 的語言統計）。
以上回答依據專案的 GitHub 資料（最近同步於 2026年9月15日）與我們的分析，不構成法律意見。
開源專案深度解析
它要解決的是 agent 執行過程不可見這件事
Claude Code 執行完一個任務之後，你看到的通常是結果：檔案改了、指令跑了、測試過了或沒過。中間發生什麼事，除非你一路盯著終端機輸出，否則很難還原。README 把這個狀態形容為 black box，作者說他在開發 CraftMyGame 這個由 AI agent 驅動的遊戲創作平台時，debug agent 行為很痛苦，所以把除錯過程視覺化，後來才獨立出來分享。
這段背景決定了 Agent Flow 的目標使用者輪廓。它不是給剛開始用 Claude Code 的人熟悉基本操作，而是給已經在跑多步驟任務、需要回答「為什麼這次執行多繞了三圈」的人。README 列出的四個使用情境都指向同一件事：理解 agent 如何拆解問題、追蹤工具呼叫鏈、找出時間花在哪、以及透過觀察累積撰寫 prompt 的直覺。最後一項比較像是副產品，前兩項才是這個工具真正站得住腳的地方。
事件從哪裡來：HTTP hook 與 rollout 檔案兩條路
Agent Flow 對兩個 runtime 採取完全不同的接入方式，這個差異值得先弄清楚。
Claude Code 這條路走的是 hooks。README 說明專案內建一個輕量 HTTP hook server，直接接收 Claude Code 送出的 events，藉此達到 zero-latency streaming。安裝流程中的 pnpm run setup 就是設定這些 hooks 的一次性步驟，VS Code 擴充套件則會在第一次開啟面板時自動設定，也可以事後從命令面板執行 Agent Flow: Configure Claude Code Hooks 重新配置。
Codex 這條路是檔案 tailing。它讀取 ~/.codex/sessions/**/rollout-*.jsonl，並且尊重 CODEX_HOME 環境變數，從 Codex 自己的事件流中取出工具呼叫、推理內容與 token 數量。README 特別用 authoritative 形容這裡的 token 計數，意思是數字來自 Codex 本身而非估算。
兩條路的性質不同。hook 是被推播的即時事件，tailing 是輪詢檔案尾端。前者延遲低但依賴 Claude Code 的 hook 機制正常運作，後者不干擾 runtime 但受限於檔案寫入的節奏。README 沒有說明兩者在畫面上的時間軸是否對齊，這一點在同時開啟兩個 runtime 時可能會造成判讀上的困擾。
第三條路是 JSONL 事件日誌。設定 agentVisualizer.eventLogPath 指向任何 .jsonl 檔，Agent Flow 就會 tail 該檔案並把事件視覺化。這條路適合事後重播，也適合拿來觀察不屬於上述兩個 runtime 的事件格式。
三個入口，選一個就好
同一個視覺化功能包了三種啟動方式，這是專案結構上比較少見的安排，但也讓選擇變得單純。
最輕的是 npx agent-flow-app，不需要 VS Code，指令跑完會在瀏覽器開啟視覺化介面，預設埠號 3001。另外兩個旗標是 --port 用來換埠、--no-open 用來阻止自動開瀏覽器、--verbose 用來顯示詳細事件日誌。README 的說明是：在另一個終端機啟動 Claude Code session，事件就會即時串進來。
要改原始碼就走建置路線：git clone 之後依序執行 pnpm i、pnpm run setup、pnpm run dev，開發伺服器在 3000 埠。這條路會同時啟動 Next.js dev server 與一個 event relay，後者接收 Claude Code 事件並透過 SSE 推送到瀏覽器。
VS Code 擴充套件是第三條路，安裝後從命令面板執行 Agent Flow: Open Agent Flow，或按 Cmd+Alt+A（Mac）／Ctrl+Alt+A（Windows、Linux）。它另外提供 Agent Flow: Open Agent Flow to Side 開在側邊欄，以及 Agent Flow: Connect to Running Agent 手動連接既有 session。
三條路的差異不只是包裝。npx 版本是唯一預設開啟匿名使用遙測的入口，README 說明這是 opt-out 且只送聚合事件，pnpm run dev 與 VS Code 擴充套件則完全不送。如果你的環境對外連線有規範，這個差別會直接影響你選哪個入口。
runtime 設定：預設同時監看，設錯不會報錯
agentVisualizer.runtime 這個設定有三個值：auto、claude、codex，預設是 auto。README 的說法是，auto 會同時監看 ~/.claude/projects/ 與 ~/.codex/sessions/，兩個 runtime 的 session 併排顯示並標註來源；如果你只用其中一套，另一套就是 harmless no-op，不會有可見效果也不需要任何操作。
非 VS Code 的入口用環境變數控制，把 AGENT_FLOW_RUNTIME 設成 claude 或 codex，不設就是兩者都看。Codex 安裝在非預設位置時，另外設定 CODEX_HOME。
這裡有個容易被忽略的行為：當你把 runtime 限定成 claude，而實際上只有 Codex 在跑，畫面不會出現「找不到 session」這類提示，就只是沒有東西。README 對 no-op 的描述是針對「兩個都看但只用一套」的情境，反過來設定錯誤時會發生什麼，材料裡沒有交代。第一次設定時建議先用預設值確認 session 有被抓到，再收窄範圍。
另外幾個設定值：agentVisualizer.devServerPort 預設 0 代表走 production 模式，agentVisualizer.eventLogPath 預設空字串，agentVisualizer.autoOpen 預設 false，要它自動開啟面板得自己打開。
它做不到的事，以及什麼時候不該用它
Agent Flow 是觀察工具，不是控制工具。README 全篇沒有提到任何介入、暫停、修改 agent 行為的能力，你能做的只有看、縮放、點擊檢視細節。想在執行途中插手，這個工具幫不上忙。
第二個限制來自 hook 機制本身。Claude Code 這條路依賴 hooks 被正確設定，而擴充套件會在第一次開啟面板時自動改寫你的 Claude Code 設定。這是對開發環境的實質變更，不是唯讀觀察。如果你在多個工具之間共用同一份 Claude Code 設定，或者你的設定檔由版本控制管理，自動改寫會產生非預期的差異。手動執行 Agent Flow: Configure Claude Code Hooks 至少讓你知道改了什麼，但 README 沒有說明這個指令具體寫入哪些欄位。
第三個限制是 v0.9.1 的發布說明直接點名的：Windows 上的 Claude Code session 探索問題。這個修正到 2026 年 7 月才發布，意味著在此之前 Windows 使用者的體驗可能不完整。如果你在 Windows 上評估這個工具，請直接從 v0.9.1 之後的版本開始。
最後，如果你的 agent 任務都是單步、幾秒內結束的操作，視覺化帶來的資訊量遠低於開啟面板的成本。這個工具處理的是有分支、有子 agent 協作、有多輪工具呼叫的長流程。
替代方案：直接讀原始事件，或看終端機輸出
最直接的替代做法是不裝任何東西，直接讀 Claude Code 與 Codex 自己留下的事件檔。Codex 的 rollout-*.jsonl 就在 ~/.codex/sessions/ 底下，Agent Flow 讀的就是這些檔案；Claude Code 的事件同樣落在 ~/.claude/projects/ 底下。用 jq 之類的工具過濾欄位，可以得到與 Agent Flow 相同的原始資訊。
兩者的差別在於呈現方式與即時性。直接讀檔案需要你自己處理 JSONL 的解析、時間排序、以及跨 session 的關聯，換來的是完整的欄位可見度，不會被視覺化層過濾掉任何東西。Agent Flow 把這些事件壓成節點圖、時間軸、transcript 面板與檔案關注熱圖，代價是你看的是它選定的投影。
另一種替代是回到終端機輸出本身。Claude Code 執行時會印出工具呼叫與結果，對短流程來說這已經夠用。Agent Flow 勝出的場景是流程長到終端機輸出被沖掉、或者同時有多個 session 在跑的時候，README 提到的 multi-session tabs 就是為此設計。
選擇的判準很簡單：你需要事後回溯一段已經結束的執行，而且需要看到分支結構，就用 Agent Flow；你只是想知道某個特定欄位的值，直接 grep 檔案更快。
授權、維護成本與升級路徑
專案採 Apache-2.0 授權，這是一個寬鬆授權，允許商業使用、修改與再散布，並包含專利授權條款。實際使用前仍應自行閱讀完整授權文本，本文不構成法律意見。
維護成本有兩個層面。安裝層面，pnpm run setup 是一次性設定，但 Claude Code hooks 的格式若隨上游變動，這個設定可能需要重跑，README 提供 Agent Flow: Configure Claude Code Hooks 作為手動重新配置的入口。執行層面，npx agent-flow-app 每次都要拉取，若你在有網路限制的環境工作，自行建置會比較穩定。
從發布節奏看，v0.8.0 在 2026 年 4 月加入 Codex runtime 支援，v0.9.0 與 v0.9.1 則在同年 7 月相隔約十五分鐘發布，前者是模型支援與 Codex 探索修正，後者是 Windows session 探索修正。這種密集的補丁發布說明上游 runtime 的變動會直接傳導到這個工具，升級不是可選項而是維持可用的必要動作。
升級前值得確認的是 release notes 是否涉及事件格式變更，因為格式一旦改變，視覺化層的解析可能需要同步調整。專案沒有在 README 中提供版本相容性矩陣，這是評估時的一個缺口。
編輯結論
如果你正在用 Claude Code 或 Codex 處理多步驟任務，而且經常需要回頭追查某一次執行到底呼叫了哪些工具、在哪裡分支，Agent Flow 值得先跑一次 npx agent-flow-app 觀察自己的 session 長什麼樣子。若你只是偶爾用 Claude Code 寫幾個檔案，或你無法接受擴充套件自動改寫 Claude Code hooks 設定，那它帶來的資訊量不足以抵銷安裝成本。動手前先確認三件事：你的 Node.js 是否為 20 以上、你的 Claude Code 安裝路徑是否為預設的 ~/.claude/projects/、以及你打算用哪個 runtime，因為 agentVisualizer.runtime 一旦設錯，畫面上就只會是一片空白而不是錯誤訊息。
社群筆記