hoangsonww/Claude-Code-Agent-Monitor

Claude Code & Codex Agent Dashboard

是什麼 – 一個自架設的 Web 應用程式，可即時監控 Anthropic 的 Claude Code 與 OpenAI 的 Codex 代理的活動。它接收代理所發出的鉤子事件（工具呼叫、子代理啟動、令牌使用量、錯誤等），將資料儲存在本地 SQLite 資料庫中，並透過 WebSockets / Server-Sent Events 將資料推送到基於 React 的 UI。UI 可視化會話、代理、工具使用情況、令牌流動、健康指標與工作流程圖，並提供桌面封裝（Electron）與 VS Code 擴充功能，方便快速存取。

---

核心功能（README 中描述）

• 即時監控 – 鉤子處理器接收來自 Claude Code / Codex 的 HTTP POST 請求，寫入 SQLite，並立即廣播更新。
• 豐富的可視化 – 使用 D3/Mermaid 圖表展示令牌使用量、工具頻率熱力圖、子代理編排的 DAG、工具流水線的桑基圖，以及健康評分儀表。
• 看板板 – 代理與會話依狀態（工作中、等待中、已完成、錯誤等）分組，懸停提示解釋會話為何處於等待狀態。
• 會話探索器 – 分頁、可搜尋的表格，列出所有記錄的會話，包含成本、模型、持續時間，以及每個會話的詳細頁面（代理、對話轉錄、時間軸、分析）。
• 國際化 – 透過 i18next 支援英文、中文、越南語、韓語與西班牙語；語言偏好在重新整理後仍保持。
• 插件市場與擴充功能 – 內建層支援 Claude Code / Codex 插件、技能與子代理，可透過本地 MCP（模型-上下文-協定）伺服器與儀表板互動。
• 桌面與 IDE 集成 – 提供 macOS（DMG）與 Windows（NSIS/便攜式）的 Electron 建構；VS Code 擴充功能可直接從編輯器開啟儀表板。
• 可觀測性堆疊 – 可選的 Prometheus 指標、Grafana 仪表板、OpenTelemetry 收集器與 Coralogix 集成，適用於生產部署。
• 部署彈性 – 提供 Docker/Podman 映像、Helm 圖表、Terraform 模組與 Kubernetes 清單；伺服器也可作為簡單的 npm start 進程運行。
• 自動化助手 – 提供 CLI 腳本、Make 目標與自動發布流水線（GitHub Actions），用於建構、測試（Vitest + React Testing Library）與發佈。

---

技術堆疊（來自徽章列表的摘要）

層	技術
後端	Node.js ≥ 22, Express 4.21, better-sqlite3（WAL 模式）, WebSocket, Server-Sent Events, Swagger-UI, OpenAPI 3, Multer（檔案上傳）
前端	React 19, TypeScript 5, Vite 7, Tailwind CSS, D3.js, Mermaid, i18next, React-Router
桌面	Electron 35 + electron-builder
可觀測性	Prometheus, Grafana, OpenTelemetry, Coralogix
基礎設施	Docker, Podman, OCI, Kubernetes ≥ 1.29, Helm, Terraform ≥ 1.7, Nginx ingress
測試 / 程式碼檢查	Vitest, React Testing Library, ESLint, Prettier
資料庫	SQLite 3（透過 better-sqlite3）
CI/CD	GitHub Actions（自動發佈）
許可證	MIT

---

誰會用到它

• 使用 Claude Code 或 Codex 建構多代理應用的開發者，需要了解代理如何呼叫工具、啟動子代理以及消耗令牌。
• 運營 LLM 驅動的程式碼助手的團隊，希望有一個中央 UI 來審計使用情況、成本與錯誤模式。
• 大規模部署 LLM 代理的運維 / SRE，希望在儀表板 UI 之外，還能獲得 Prometheus 指標與 Grafana 仪表板。
• 研究代理編排、工具使用模式或跨會話令牌流動的研究人員。

---

快速入門（來自 README 的概要）

1. 克隆倉儲

   git clone https://github.com/hoangsonww/Claude-Code-Agent-Monitor.git
   cd Claude-Code-Agent-Monitor
   

2. 安裝相依性

   npm ci   # 安裝後端與前端套件
   

3. 執行伺服器（開發模式）

   npm run dev   # 啟動 Express + SQLite + WebSocket + 熱重載 Vite UI
   

4. 設定 Claude Code / Codex
   • 將提供的鉤子 URL（例如 http://localhost:3000/hook）加入代理的原生鉤子設定中，以便在工具使用、停止等事件時發送 POST 請求。
5. 開啟儀表板
   • 訪問 http://localhost:5173（Vite 開發伺服器）或啟動打包的 Electron 應用。
6. 可選：生產部署
   • 建構 UI：npm run build
   • 執行編譯後的 Express 伺服器：npm start
   • 或使用提供的 Dockerfile / Helm 圖表進行容器化/K8s 部署。

---

更多資訊來源

• Wiki – 實用手冊、自動化腳本與故障排除指南： https://github.com/hoangsonww/Claude-Code-Agent-Monitor/wiki
• Docs 檔案夾 – 詳細的 API 規格、i18n 指南、伺服器架構與 MCP 集成說明。
• 本地化 README – 中文、越南語、韓語、西班牙語版本，提供地區特定提示。

---

許可證

MIT – 免費用於個人、學術或商業用途，需註明作者。