如果你每天都在用 Claude Code、Codex 或 Cursor 这类 AI 编码助手，多半遇到过这样的烦恼：Agent 在后台"闷头干活"，你却不知道它卡住了没有、烧掉了多少 Token、离上下文爆满还有多远。Claude-Code-Agent-Monitor（常简称为 CCAM）就是一个专为 AI 编码 Agent 打造的实时监控仪表盘：它把每一次会话（Session）、Agent 状态、工具调用、Token 成本与子代理协作全部可视化，通过 WebSocket 实时推送到浏览器里，让你从"盯终端"变成"看仪表盘"。这篇文章带你用 10 分钟读懂这个项目的核心价值、功能亮点，以及最快的上手路径。

它是什么：一张实时更新的"AI 指挥中心"

Claude-Code-Agent-Monitor 基于 Node.js + Express + React + SQLite 构建，同时支持Claude Code、Codex 和 Cursor三大 AI 编码助手。整体数据链路非常清爽：

1. 钩子（Hooks）与本地文件监听：AI 助手在会话开始、工具调用、回合结束、子代理完成等节点发出 JSON 事件，Codex 的 rollout 日志也会被增量读取；
2. 服务器：Express 服务在 SQLite 事务中写入会话、Agent 和事件，自动创建记录、计算 Token 与成本；
3. 仪表盘：React 前端通过 WebSocket 接收推送即时重绘——没有轮询，延迟接近 0ms。

也就是说：你敲下回车的那一刻，仪表盘的卡片就已经在动了。完整架构细节见 ARCHITECTURE.md。

为什么 AI 程序员需要"监控"Agent

把 Agent 交给后台跑任务，最怕的是"失控感"：

• 🕳️黑盒：Agent 是在努力干活、在等你输入，还是报错了卡死？终端里看不出来；
• 💸成本：一个长会话消耗了多少 Token、折合多少钱，跑完才知道；
• 🧵多任务：同时开多个会话、派出一堆子代理（Subagent），整体进展全靠脑内记账；
• 🔍回溯难：出了问题只能翻 JSONL 日志和终端历史，效率极低。

CCAM 的价值，就是把这些"看不见"的过程变成一块随时可看的实时仪表盘——状态、成本、错误、等待原因，一目了然。

核心功能：5 个最值得一看的能力

1️⃣ 实时看板：Agent 在忙还是在等，一列看懂

Kanban Board 把 Agent 按状态分成 Working / Waiting / Completed / Error 四列，Session 视图则是五列。最贴心的是黄色的Waiting 列：Agent 卡在"等你输入"时会被单独标出，悬停还能看到原因——是权限确认、回合结束，还是被中断。每张卡片直接显示模型、成本与当前工具，多任务并行时再也不用心跳式刷新。

2️⃣ 会话详情与对话回放：把 Agent 的"内心戏"完整还原

点进任意会话，会看到实时刷新的事件/工具调用/子代理统计、Token 流向条，以及完整的对话回放：Markdown 渲染、代码高亮、工具调用以不同样式呈现，连中途排队输入的消息都会按 Claude 实际收到的位置放置。配合时间线视图，任何一次异常都能定位到具体事件。

3️⃣ 分析面板：Token 花在哪，一张图说清

Analytics 页面按模型统计 Token 用量与成本、统计工具调用频率、绘制活跃热图与会话趋势。子代理卡片显示的是各自的成本而非会话总额，主代理卡片才代表整个会话——成本归因很严谨。定价规则可在设置页自由编辑，甚至支持"限时优惠费率"的历史回溯计价。

4️⃣ 工作流可视化：子代理协作不再是"一团乱麻"

Workflows 页面用 D3.js 呈现 11 个交互视图：Agent 编排 DAG、工具执行桑基图、协作网络、错误传播图、并发时间线等，还能自动"检测"出重复出现的编排模式并给出解释。对于由Workflow工具拉起的动态工作流群，每个 run 的每个 Agent 的 Token、工具调用与耗时都能展开查看。

5️⃣ 告警、通知与桌面端：监控不止于"看"

告警引擎支持事件模式、长时间不活跃、Agent 卡死、Token 阈值四类规则，触发后可推送到 Slack、Discord、Telegram 等 14 种 Webhook 渠道；Web Push 通知即使浏览器最小化也能送达。如果你连网页都不想开着，还有macOS / Windows 原生桌面应用：托盘图标点一下就能看会话/Agent/事件快照，支持开机自启，首次启动自动装好钩子，零配置即可用。

快速上手：10 分钟跑通全流程

前置要求：Node.js ≥ 22.22（推荐 24 LTS）、npm ≥ 9.0。

第一步：克隆并安装（约 5 分钟）

git clone https://gitcode.com/gh_mirrors/cl/Claude-Code-Agent-Monitor cd Claude-Code-Agent-Monitor npm run setup

第二步：安装监控钩子

npm run install-hooks

交互式界面里用方向键 + 空格选择Claude Code、Codex或两者都装。安装器只写入本项目的钩子条目，你已有的其他钩子不受影响。

第三步：启动并打开仪表盘

npm run dev # 开发模式：http://localhost:5173 # 生产模式： npm run build && npm start # http://localhost:4820

想零数据先逛界面？执行npm run seed即可写入 8 个示例会话、23 个 Agent 和 106 条事件。偏好 Docker 的用户一条docker compose up -d --build也能跑起来（详见 DEPLOYMENT.md）。

进阶玩法：给仪表盘装上"超能力"

• 🖥️ccamCLI：终端里直接操作仪表盘——ccam overview实时快照、ccam sessions查会话、ccam cost看成本，还支持离线直读数据库。完整参考见 docs/CLI.md；
• 🔌本地 MCP 服务器：把 100+ 监控工具暴露给 Claude Code / Codex 自己用，AI 可以"自查仪表盘"，见 mcp/README.md；
• 🧩插件市场：14 个官方插件覆盖成本守护、效率报告、质量 SLO、会话取证等场景；
• 🛰️多机收集：Remote Data Sources 通过 SSH 把其他机器上的会话镜像到同一块仪表盘，一台电脑掌握全团队动态。

关键路径速查

写在最后

AI 编码 Agent 正在从"聊天框里的助手"变成"后台干活的同事"，而管理同事需要的不是盯梢，是仪表盘。Claude-Code-Agent-Monitor 用实时看板、成本分析、告警推送和桌面端，把多会话、多子代理的复杂状态压缩成一块清晰的屏幕。对于重度使用 Claude Code / Codex 的 AI 程序员来说，它几乎是"装上就不想摘"的效率基础设施——花 10 分钟装好，省下的将是每天反复刷新终端的时间。