claude-code-agent-monitor

用途

Claude Code Agent Monitor 是一个全栈监控平台，用于实时跟踪 Claude Code 智能体的活动。它记录会话、工具使用、子智能体编排和性能指标，帮助开发者了解 Claude Code 在任务执行过程中的行为。

主要能力

实时会话跟踪，带实时智能体卡片
工具使用分析（柱状图、热力图、D3.js 可视化）
子智能体编排流程图（Mermaid）
智能体状态看板（Kanban）
浏览器通知（Web Push API + VAPID）
RESTful API + Swagger/OpenAPI 文档
用于仪表盘自省的 MCP 服务器
VS Code 扩展 + macOS/Windows 原生应用
国际化支持（英语、中文、越南语、韩语、西班牙语）
Prometheus 指标导出 + Grafana 仪表盘
Kubernetes、Docker、Terraform 部署方案

技术栈

Node.js + Express + better-sqlite3（WAL 模式）+ WebSocket（RFC 6455）+ React 18 + TypeScript + Vite + TailwindCSS + Electron（桌面应用）。

使用方式

前置条件

Node.js ≥ 20.x
Python ≥ 3.6（用于 hook 处理脚本）
已安装并配置 Claude Code

快速开始

git clone https://github.com/hoangsonww/Claude-Code-Agent-Monitor.git
cd Claude-Code-Agent-Monitor
npm install
npm run build
npm start
# 服务器运行在 http://localhost:3000

开发模式（热重载）：

# 终端 1：启动后端服务器
npm run dev

# 终端 2：启动 React 前端的 Vite 开发服务器
npm run dev:client
# 前端运行在 http://localhost:5173

Hook 处理器设置

Python hook 处理器捕获 Claude Code 事件并转发到仪表盘服务器。

复制 hook 脚本到 Claude Code hooks 目录：

# macOS/Linux
cp hook-handler/hook_handler.py ~/.claude-code/hooks/

# Windows
copy hook-handler\hook_handler.py %USERPROFILE%\.claude-code\hooks\

在 hook_handler.py 中配置 hook 端点：

DASHBOARD_URL = os.getenv("DASHBOARD_URL", "http://localhost:3000")

在 Claude Code 配置（~/.claude-code/config.json）中启用 hooks：

{
  "hooks": {
    "enabled": true,
    "onToolUse": "~/.claude-code/hooks/hook_handler.py",
    "onSessionStop": "~/.claude-code/hooks/hook_handler.py"
  }
}

测试 hook：

python3 hook_handler.py --test
# 应 POST 到 http://localhost:3000/api/events

环境变量配置

在项目根目录创建 .env 文件：

PORT=3000
HOST=0.0.0.0
NODE_ENV=production
DB_PATH=./data/agent-monitor.db
WS_PORT=3001
WS_PATH=/ws
VAPID_PUBLIC_KEY=your_public_key_here
VAPID_PRIVATE_KEY=your_private_key_here
VAPID_SUBJECT=mailto:your-email@example.com
CORS_ORIGINS=http://localhost:5173,http://localhost:3000
DATA_RETENTION_DAYS=30
METRICS_ENABLED=true
METRICS_PORT=9090

API 参考

服务器在 http://localhost:3000/api-docs 提供 Swagger 文档。主要端点：

POST /api/events：接收来自 Claude Code 的 hook 事件
GET /api/sessions：分页列出所有会话
GET /api/sessions/:id：获取会话详情（含工具使用与子智能体）
GET /api/agents：列出所有智能体及活动摘要
GET /api/tools/stats：工具使用统计（次数、时长、成功率）
GET /api/health：健康检查（数据库状态、WebSocket 连接数、系统指标）
DELETE /api/sessions/:id：删除会话及其关联事件

WebSocket 事件

连接 ws://localhost:3001/ws 接收实时更新。客户端发送订阅消息：

{
  "type": "subscribe",
  "channels": ["sessions", "tools", "agents"]
}

事件类型：session_start、session_stop、tool_use、subagent_spawn、agent_status_change。

Hook 事件格式

工具使用事件示例：

{
  "type": "tool_use",
  "sessionId": "sess_abc123",
  "agentId": "agent_main",
  "toolName": "file_edit",
  "timestamp": "2026-08-02T22:01:04Z",
  "metadata": {
    "path": "/src/components/Dashboard.tsx",
    "linesChanged": 15,
    "duration_ms": 230,
    "success": true
  }
}

会话停止事件示例：

{
  "type": "session_stop",
  "sessionId": "sess_abc123",
  "agentId": "agent_main",
  "timestamp": "2026-08-02T23:00:00Z",
  "metadata": {
    "duration_seconds": 3600,
    "toolsUsed": 47,
    "subagentsSpawned": 3,
    "exitReason": "user_stop"
  }
}

子智能体生成事件示例：

{
  "type": "subagent_spawn",
  "sessionId": "sess_abc123",
  "parentAgentId": "agent_main",
  "subagentId": "agent_test_runner",
  "timestamp": "2026-08-02T22:15:00Z",
  "metadata": {
    "purpose": "run_vitest_suite",
    "context": {
      "testFile": "src/components/Dashboard.test.tsx"
    }
  }
}

适用场景

需要观察 Claude Code 智能体在长时间任务中的实时活动
分析工具调用模式、耗时与成功率
追踪子智能体的生成与编排流程
通过 Prometheus/Grafana 集成到现有监控体系
在 VS Code 或桌面应用中查看监控数据

限制

需要 Node.js ≥ 20.x 与 Python ≥ 3.6 环境
需要安装并配置 Claude Code 及 hooks
数据默认保留 30 天（可通过 DATA_RETENTION_DAYS 调整）
关于收费、价格、平台支持范围等具体信息，资料中暂未提供