Agents Observe
为 Claude Code 与多智能体（multi-agent）会话提供实时可观测性面板，让每个子代理、每次工具调用和 Token 消耗一目了然。
- Star 数
- ★ 705
- 最近更新
- 1 个月前
- License
- MIT
- 主语言
- TypeScript
- FA 评分
- 55/100 · 缺口较多
30 秒速览
- 运行形态
- 可在哪里用
- 平台专用Claude Code
- 费用
- 免费，无需付费服务
- 上手难度
- 中 · 需要几步配置
- 开始前需要
- 典型场景
- 运行协调者模式的 Claude Code 用户同时派生代码审查、测试运行和文档子代理，需要在面板上实时看到每个子代理在做什么
- 不适合
- 不想安装 Docker 或 Node.js 的用户
- 需要监控 Codex、OpenClaw 等非 Claude Code 代理的团队
- 需要完全离线、不依赖本地端口与 WebSocket 的环境
- 源码审查
- 55/100 · 缺口较多
这个 Agent 能做什么，适合哪些场景？
Agents Observe（GitHub: simple10/agents-observe）是一个面向 Claude Code 会话的实时可观测性仪表盘，以 Claude Code 插件形式分发，也可脱离插件独立运行。它通过 Claude Code Hooks 捕获每个事件（工具调用、提示、停止、子代理生命周期），经 observe_cli.mjs 通过 HTTP POST 发送到一个 Hono + SQLite + WebSocket 的 Node 服务器，再由 React 19 客户端实时展示。仪表盘支持强大的过滤、搜索与可视化，可展开查看事件的完整载荷（命令与结果），查看子代理与父代理的层级关系，并通过会话回放追踪历史，最新版本（0.9.7）还增加了会话 Token 用量与成本统计。生产模式下服务器以 Docker 容器运行，默认面板地址为 http://localhost:4981，数据默认存放在插件数据目录或 ~/.agents-observe/ 下的 SQLite 数据库中。如果你的团队经常运行多代理并行任务，需要事后排查或实时监控代理行为，这个工具直接针对该痛点。
工作流程为：Claude Code Hooks 在每个事件上触发 hooks.sh 与 observe_cli.mjs，后者从 stdin 读取原始事件，经由 hooks/scripts/lib/agents/<class>.mjs 中的 buildHookEvent() 构建包含代理类别标志（如 meta.isNotification）的事件封套，POST 到 API 服务器。服务器提取结构化字段（事件类型、工具名、代理 ID），存储代理元数据（名称、描述、类型、父子关系），写入 SQLite（observe.db），并将事件转发给订阅该会话的 WebSocket 客户端。React 客户端首次加载时通过 REST API 拉取事件，之后通过 WebSocket 增量接收；客户端将 PreToolUse 与 PostToolUse 合并为单行展示，所有代理状态（状态、事件计数、耗时）均从事件流推导。可通过 /observe 技能（view、stats、status、start、stop、restart、logs、debug）在 Claude 中管理服务器。
- 运行协调者模式的 Claude Code 用户同时派生代码审查、测试运行和文档子代理，需要在面板上实时看到每个子代理在做什么
- 开发者调试一个深度嵌套的并行代理执行中出现的问题，需要回放完整事件时间线与载荷定位破坏性命令
- 团队负责人想统计各会话的 Token 用量与成本分布，通过会话统计弹窗评估支出
- 独立开发者离线运行 Codex 或手动 CLI 场景（数据目录 ~/.agents-observe/），需要独立安装方式监控代理事件
- 工程师需要排查插件服务器故障，用 /observe debug 检查服务器健康、Docker 容器日志、mcp.log 和 cli.log
如何安装或部署这个 Agent？
前提：主机需安装 Docker、Node.js 和 Bash。以 Claude Code 插件方式安装：
bash
# 将本仓库添加为插件市场
claude plugin marketplace add simple10/agents-observe# 安装插件
claude plugin install agents-observe插件会自动启动 MCP 服务器并捕获事件。数据默认存于 ~/.claude/plugins/data/agents-observe-agents-observe/（市场安装）。如需自定义数据位置，在 ~/.claude/settings.json 中设置 env.AGENTS_OBSERVE_LOCAL_DATA_ROOT。
独立安装（开发或非插件方式）：
bash
git clone https://github.com/simple10/agents-observe.git agents-observe
cd agents-observebrew install just # 如未安装
just start # 启动 Docker 容器
# 或本地开发：just install && just dev
独立模式还需将 .claude/settings.json 中的 hooks 复制到项目或用户级 Claude Code 设置中，并将 $CLAUDE_PROJECT_DIR 路径指向安装位置。
如何使用这个 Agent？
插件安装后直接运行 claude，服务器自动启动并捕获事件；浏览器打开 http://localhost:4981 查看仪表盘（开发模式为 http://localhost:5174）。在 Claude 中使用 /observe 技能：/observe status 查看服务器健康与版本，/observe view 打开当前会话，/observe stats 打开 Token 统计，/observe logs 查看 Docker 日志，/observe debug 诊断问题。独立模式下可用 just 命令：just health 检查服务器，just test-event 发送测试事件，just dev 热重载开发，just db-reset 重置数据库。常用环境变量：AGENTS_OBSERVE_SERVER_PORT（默认 4981）、AGENTS_OBSERVE_PROJECT_SLUG、AGENTS_OBSERVE_API_BASE_URL、AGENTS_OBSERVE_NOTIFICATION_ON_EVENTS，完整列表见 docs/ENVIRONMENT.md。
这个 Agent 有哪些优点和局限？
- 实时流式展示每个工具调用（PreToolUse → PostToolUse 含结果），而终端只能看到一小部分活动，子代理通常完全不可见
- 展示完整的代理层级关系，能看出哪个子代理由哪个父代理派生，这是多数日志方案不具备的
- 事件存入 SQLite 支持历史会话回放与跨会话行为模式分析，调试相当于"时间旅行"
- 0.9.7 起内置 Token 用量与成本分解统计，可直接评估代理运行成本
- 以官方插件市场方式一键安装，升级自动保留数据库，并提供 /observe debug 自诊断
- 强制依赖 Docker 运行服务器，同时需要 Node.js 和 Bash，任一缺失插件将无法正常加载
- 核心基于 Claude Code Hooks，对其他代理框架（Codex、OpenClaw、pi-code）的支持仍在路线图中尚未实现
- 多占一个本地端口（默认 4981，占用时会自动换端口），生产与开发模式端口不同可能造成混淆
- 从 ≤0.9.8 旧版本升级需要依赖首次启动时的数据库迁移扫描，存在迁移风险（迁移记录见 .migrated-from.）
- 服务器跟踪会话状态但不跟踪代理状态，代理状态完全由客户端从事件流推导，实时性依赖 WebSocket 连接（断线每 3 秒重连）
这个 Agent 与同类方案有什么区别？
README 提到相关项目：Agent Super Spy（作者同为此仓库作者，提供可本地或远程运行的完整代理可观测性栈）、Multi-Agent Observability System（本项目的灵感来源）、Claude DevTools（针对 Claude 会话文件的可视化工具，需在本地机器运行）。
与相关度最高的同类 agent 并排比较关键指标。
| Agent | 源码审查 | 形态 / 费用 | Star | 最近更新 | 主语言 | 完整支持的平台 |
|---|---|---|---|---|---|---|
| Agents Observe 当前 | 55 · 缺口较多 | Agent 插件 / 技能免费 | ★ 705 | 1 个月前 | TypeScript | Claude Code |
| Claw-Empire AI 公司控制台 | 72 · 存在缺口 | 命令行工具免费 + 模型费 | ★ 1.4k | 7 个月前 | TypeScript | Codex · Claude Code · OpenAI API · Claude API |
| Claude Code 多代理可观测性系统 | 35 · 缺口较多 | 自托管服务免费 + 模型费 | ★ 1.6k | 8 个月前 | Python | Claude Code |
| OSS Autopilot | 83 · 表现良好 | Agent 插件 / 技能免费 | ★ 23 | 今天 | TypeScript | Claude Code · Claude.ai |
FollowAgents 如何评估这个 Agent？
查看各维度的扣分理由
数据流文档较清晰（本地SQLite、环境变量、存储路径、迁移记录），外部效果限于本机端口，无远程外传证据；但该工具完整捕获所有hook事件payload（含命令、文件读取内容），无脱敏或保留策略说明，捕获面为全部事件而非最小必要，扣分明显；依赖安全仅有allowScripts白名单，无审计证据；回滚仅有db-reset，无通用回滚。
故障排查章节和/observe debug命令较为完善，failure_messages给2；但自相矛盾处可见：副标题宣称支持Codex而ROADMAP又列为待办，README中出现0.9.7版本注记而package.为0.9.12，还有重复的'just health'行，self_consistency扣至1；依赖Docker+Node+Bash三件套，缺失即无法加载，dependency_availability仅1。
面向Claude Code多智能体会话观测，受众与场景描述清楚；hook事件、端口、路径、环境变量均可配置，trigger_precision与environment_fit可给2；但能力边界表述矛盾（Codex既在宣传又在路线图），known/边界说明不一致故capability_boundaries仅1。
README结构完整（快速开始、架构、项目结构、排错），install_notes和information_architecture可给3；MIT LICENSE明确署名Joe Johnston，license给3；发布流程引用CHANGELOG.md并有tag发布流水线，versioning给2；但已知限制无专门章节，维护者/贡献/更新承诺信息缺失且发布者未验证，maintenance_responsibility仅1。
仪表盘功能（实时流、过滤、agent层级、token统计、回放）描述具体且通过截图/演示佐证，output_usability与marginal_value给2；但运行需Docker+Node常驻容器与hook注入，成本不低，且有fresh-install测试框架证明安装链路复杂，cost_benefit保持2未加分。
架构声明与项目结构、测试夹具（健康端点/api/health、sessions接口）可交叉印证，claim_traceability与cross_source_corroboration给2；但关键实现文件（observe_cli.mjs、server源码、CHANGELOG正文）未在证据中，README的0.9.7与package.的0.9.12版本不一致，事实与推断难以严格分离，fact_inference_separation仅1。
- 该工具会完整捕获所有hook事件payload（包括执行的命令和读取的文件内容）并存储到本地SQLite，使用前请确认无脱敏/加密需求未被满足，并注意数据库文件的访问权限。
- 运行需要Docker、Node和Bash三者齐备，任一缺失插件将无法加载；服务器默认监听本机端口4981，若改动AGENTS_OBSERVE_BIND为0.0.0.0请注意网络暴露面。
- 文档存在版本不一致（README提及0.9.7，package.为0.9.12）与Codex支持表述矛盾，实际功能以执行验证为准。
- 发布者未经验证，无明确维护承诺与贡献流程，长期维护风险自担。
最近版本
来自该项目 GitHub Releases 的最新发布记录，说明为上游原文摘录，未经本站改写或测试。
-
发布说明摘录
This release tightens default security by binding the server to loopback, restricting CORS, and rejecting cross-origin WebSocket connections. It also fixes running the dashboard on Windows and SELinux hosts, and improves structured output summaries. Breaking Changes The server now binds to loopback (localhost) and restricts CORS by default, so the dashboard is no longer reachable from other machines or cross-origin pages out of the box. If you access the dashboard remotely or from a different origin, you'll need to explicitly configure the server's host binding and allowed origins to opt …在 GitHub 查看 ↗ -
发布说明摘录
This release introduces the fun new Constellation UI home-page view — an activity bubble visualization. It adds first-class support for Hermes agents, including dedicated event rendering, session stats, and model pricing, alongside a redesigned collapsible conversation thread with navigation and stable scrolling. Features - Added the Constellation dashboard theme; it's now the default home-page view with a toggle to switch to previous List view. …在 GitHub 查看 ↗ -
发布说明摘录
This release adds token cost attribution for subagents and workflows, so the tokens they consume are now traced back to the prompt that triggered them. It also improves Workflow tool tracking by correctly pairing pre- and post-execution events and rendering their details in the dashboard. Features - Subagent and workflow token costs are now attributed to the originating prompt, giving you accurate per-prompt cost breakdowns.在 GitHub 查看 ↗
常见问题
必须安装 Docker 吗？
just start-local 或 start.mjs 不经 Docker 本地启动服务器，但仍需 Node.js 和 Bash。支持 Claude Code 以外的代理工具吗？
数据存在哪里，升级会丢数据吗？
端口 4981 被占用怎么办？
面板上看不到事件怎么排查？
just health 或 /observe status 确认服务器在运行；确认 hooks 已复制到项目设置；用 just test-event 发送测试事件验证链路；WebSocket 断线时客户端每 3 秒自动重连，重连后事件会补齐。