Agents Observe
Real-time observability dashboard for Claude Code and multi-agent sessions, making every subagent, tool call, and token cost visible as it happens.
Data flow is well documented (local SQLite, env vars, storage paths, migration record); external effects are confined to localhost with no evidence of remote exfiltration. However, the tool captures full payloads of every hook event (commands, file-read contents) with no redaction or retention policy, and the capture surface is all events rather than least-privilege — clear deductions. Dependency security shows only an allowScripts allowlist with no audit evidence; rollback is limited to db-reset.
Troubleshooting and /observe debug are solid, so failure_messages gets 2; but visible inconsistencies exist: the tagline claims Codex support while the ROADMAP lists it as to-do, the README cites version 0.9.7 while package. says 0.9.12, and there is a duplicated 'just health' line — self_consistency drops to 1. The hard triple dependency on Docker+Node+Bash (fails to load if any is missing) limits dependency_availability to 1.
Audience and scenario (multi-agent Claude Code observability) are clear; hooks, ports, paths and env vars are configurable, so trigger_precision and environment_fit get 2. But capability boundaries are stated inconsistently (Codex both advertised and pending), so capability_boundaries stays at 1.
README is thorough (quick start, architecture, project structure, troubleshooting) — information_architecture and install_notes earn 3; MIT LICENSE names Joe Johnston, license gets 3; a tag-driven release workflow extracts CHANGELOG.md sections, versioning gets 2. But there is no dedicated limitations section and no maintainer/contributing/update commitment, with an unverified publisher — maintenance_responsibility is only 1.
Dashboard features (live streaming, filtering, agent hierarchy, token stats, replay) are concretely described and corroborated by screenshots/demo, so output_usability and marginal_value get 2. But running requires a persistent Docker container plus Node hooks, a non-trivial cost, and the fresh-install harness itself shows how complex the install chain is — cost_benefit holds at 2 without a bonus.
Architecture claims cross-check against the project structure and the test harness (health endpoint, sessions API), giving claim_traceability and cross_source_corroboration 2. But the key implementation files (observe_cli.mjs, server source, CHANGELOG body) are not in evidence, and the 0.9.7-vs-0.9.12 version mismatch makes fact/inference separation weak — fact_inference_separation is 1.
- The tool captures full payloads of all hook events (including executed commands and file-read contents) into a local SQLite DB; verify redaction/encryption needs before use and mind DB file permissions.
- Requires Docker, Node, and Bash simultaneously; the plugin fails to load if any is missing. The server listens on localhost:4981 by default — if you set AGENTS_OBSERVE_BIND to 0.0.0.0, watch network exposure.
- Documentation has inconsistencies (README cites 0.9.7 while package. says 0.9.12, and Codex support is both advertised and listed as roadmap); verify actual functionality by execution.
- Publisher is unverified with no explicit maintenance commitment or contribution process; long-term maintenance risk is on the user.
What does this agent do, and when should you use it?
Agents Observe (GitHub: simple10/agents-observe) is a real-time observability dashboard for Claude Code sessions, distributed as a Claude Code plugin and also runnable standalone. It captures every hook event — tool calls, prompts, stops, subagent lifecycle — via Claude Code Hooks, POSTs them through observe_cli.mjs to a Hono + SQLite + WebSocket Node server, and renders them live in a React 19 client. The dashboard offers powerful filtering, searching, and visualization of multi-agent sessions, with expandable full payloads (commands and results), parent/child agent hierarchy, session replay, and — since version 0.9.7 — token usage and cost breakdowns per session. In production the server runs as a Docker container with the dashboard served at http://localhost:4981; events persist to a SQLite database under the plugin data directory or ~/.agents-observe/. If your team routinely runs parallel multi-agent work and needs live monitoring or post-hoc debugging of agent behavior, this tool targets exactly that problem.
The flow works as follows: Claude Code Hooks fire on every event and invoke hooks.sh plus observe_cli.mjs, which reads the raw event from stdin and dispatches through buildHookEvent() in hooks/scripts/lib/agents/<class>.mjs to build an envelope with agent-class-aware flags (e.g. meta.isNotification), then POSTs it to the API server. The server extracts structural fields (event type, tool name, agent ID), stores agent metadata (name, description, type, parentage), persists everything to SQLite (observe.db), and forwards events to WebSocket clients subscribed to the relevant session. The React client fetches events via REST on initial load, then appends real-time updates via WebSocket; it merges PreToolUse and PostToolUse into a single row and derives all agent state (status, event counts, timing) from the event stream. The /observe skills (view, stats, status, start, stop, restart, logs, debug) manage the server from inside Claude.
- A Claude Code user running a coordinator pattern that spawns code reviewer, test runner, and documentation subagents in parallel, who needs to watch each subagent work live on a dashboard
- A developer debugging a failure three agents deep in a parallel execution who needs to replay the exact event timeline with full payloads to trace a destructive command
- A team lead who wants per-session token usage and cost breakdowns, viewed through the session stats modal, to assess spend
- A solo developer running Codex or a manual CLI outside Claude (data under ~/.agents-observe/) who needs the standalone installation to monitor agent events
- An engineer troubleshooting the plugin server using /observe debug to check health, Docker container logs, mcp.log, and cli.log
What are this agent's strengths and limitations?
- Streams every tool call (PreToolUse → PostToolUse with results) in real time, whereas the terminal shows only a fraction of activity and subagents are normally invisible
- Shows the full agent hierarchy — which subagent was spawned by which parent — a capability most log-based approaches lack
- Events persist to SQLite enabling historical session replay and cross-session behavior pattern analysis, making debugging effectively time travel
- Built-in token usage and cost breakdowns per session since 0.9.7, directly usable for spend evaluation
- One-command install via the official plugin marketplace with automatic DB preservation on upgrade and self-diagnosis via /observe debug
- Hard dependency on Docker for the server, plus Node.js and Bash — the plugin fails to load properly if any is missing
- Core mechanism is built on Claude Code Hooks; support for other frameworks (Codex, OpenClaw, pi-code) is roadmap-only and not yet implemented
- Occupies a local port (default 4981, auto-reassigned if taken), and dev vs production ports differ, which can cause confusion
- Upgrading from pre-fix versions (≤0.9.8) relies on a first-start DB migration scan, a real migration risk (recorded in .migrated-from.)
- The server tracks session status but not agent status — agent state is derived client-side from the event stream, and live updates depend on WebSocket (reconnects every 3 seconds)
How do you install or deploy this agent?
Prerequisites: Docker, Node.js, and Bash on the host. Plugin install:
bash
# Add this repo as a marketplace
claude plugin marketplace add simple10/agents-observe# Install the plugin
claude plugin install agents-observeThe plugin auto-starts the MCP server and captures events. Data lands in ~/.claude/plugins/data/agents-observe-agents-observe/ (marketplace install). To relocate data, set env.AGENTS_OBSERVE_LOCAL_DATA_ROOT in ~/.claude/settings..
Standalone install (dev or non-plugin):
bash
git clone https://github.com/simple10/agents-observe.git agents-observe
cd agents-observe
brew install just # if needed
just start # start the Docker container
# or local dev: just install && just devStandalone mode also requires copying the hooks from .claude/settings. into your project- or user-level Claude Code settings and pointing $CLAUDE_PROJECT_DIR paths at your install location.
How do you use this agent?
After the plugin install, just run claude — the server starts automatically and captures events; open http://localhost:4981 in a browser (dev mode: http://localhost:5174). Use the /observe skills inside Claude: /observe status for server health and version, /observe view to open the current session, /observe stats for token stats, /observe logs for Docker logs, /observe debug to diagnose issues. In standalone mode use just commands: just health to check the server, just test-event to send a test event, just dev for hot-reload development, just db-reset to wipe the database. Key environment variables: AGENTS_OBSERVE_SERVER_PORT (default 4981), AGENTS_OBSERVE_PROJECT_SLUG, AGENTS_OBSERVE_API_BASE_URL, AGENTS_OBSERVE_NOTIFICATION_ON_EVENTS; the full list is in docs/ENVIRONMENT.md.
How does this agent compare with similar options?
The README references related projects: Agent Super Spy (by the same author, a full observability stack for agents, runnable locally or remotely), Multi-Agent Observability System (the inspiration for this project), and Claude DevTools (visualization for Claude session files, requires running on the local machine).
FAQ
Is Docker required?
just start-local or start.mjs, but Node.js and Bash are still required.Does it support agents other than Claude Code?
Where is data stored, and is it preserved on upgrade?
What if port 4981 is already in use?
How do I troubleshoot missing events in the dashboard?
just health or /observe status; confirm hooks are copied into your project settings; verify connectivity with just test-event; note that if WebSocket drops, the client reconnects every 3 seconds and refetches missed events.