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 – 免费用于个人、学术或商业用途，需注明作者。