Agents Observe
Real-time observability dashboard for Claude Code agents.
Includes powerful filtering, searching, and visualization of multi-agent sessions.
Demo video
Quick Start
Install as a claude code plugin:
# Add this repo as a marketplace
claude plugin marketplace add simple10/agents-observe
# Install the plugin
claude plugin install agents-observe
# Then just run claude
# The plugin will auto start the MCP server and capture events
claude
# Use the /observe skill in claude to check status, restart the server, etc.
> /observe status
> /observe debug
> /observe logs
> /observe restart
# Open the dashboard UI in a browser
open http://localhost:4981
Default dashboard URL: http://localhost:4981
Prerequisites
- Docker (required — the server runs as a container)
- Node.js (required — hook scripts run via
node)
If docker or node are not installed on your host, the plugin will fail to properly load.
Use the /observe debug claude command to help troubleshoot and fix installation issues.
Plugin Skills
| Skill | Description |
|---|
/observe | Open the dashboard URL and check if the server is running |
/observe status | Show server health, version, runtime, and config details |
/observe start | Start the server |
/observe stop | Stop the server |
/observe restart | Restart the server |
/observe logs | Show recent Docker container logs |
/observe debug | Diagnose server issues (health, docker logs, mcp.log, cli.log) |
Why observability matters
When Claude Code runs autonomously — spawning subagents, calling tools, reading files, executing commands — you have no visibility into what's actually happening. The terminal shows a fraction of the activity. Subagents are invisible. Tool calls blur together. And when something goes wrong three agents deep in a parallel execution, you're left reading through logs after the fact.
Claude Observe captures every hook event as it happens and streams it to a live dashboard. You see exactly what each agent is doing, which tools it's calling, what files it's touching, and how subagents relate to their parents. In real time.
This matters because:
- Multi-agent work is opaque. A coordinator spawns a code reviewer, a test runner, and a documentation agent in parallel. Without observability, you only see the final result. With it, you watch each agent work and catch problems as they happen.
- Tool calls are the ground truth. The assistant's text output is a summary. The actual tool calls — the Bash commands, file reads, edits, grep patterns — tell you what Claude is really doing. Claude Observe shows you both.
- Debugging is time travel. When a subagent makes a bad edit or runs a destructive command, you need to trace back through the exact sequence of events. The event stream gives you that timeline with full payloads.
- Sessions are ephemeral, but patterns aren't. By capturing events across sessions, you can see how agents behave over time, which tools they favor, and where they get stuck.
What you can do
- Watch tool calls stream in as they happen (PreToolUse → PostToolUse with results)
- See the full agent hierarchy — which subagent was spawned by which parent
- Filter by agent, tool type, or search across all events
- Expand any event to see the full payload, command, and result
- Click timeline icons to jump to specific events in the stream
- Browse historical sessions with human-readable names (e.g., "twinkly-hugging-dragon")
Architecture
Claude Code Hooks → observe_cli.mjs → API Server (SQLite) → React Dashboard
(agent-lib build) (HTTP POST) (parse + store) (WebSocket live)
observe_cli.mjs reads the raw event from stdin and dispatches to an agent-class-specific lib (hooks/scripts/lib/agents/<class>.mjs) whose buildHookEvent() constructs the envelope — including agent-class-aware flags like meta.isNotification / meta.clearsNotification — then POSTs it to the server. The server applies those flags mechanically to its stored state (e.g. pending_notification_ts) and forwards events to subscribed WebSocket clients; it stays agent-class-neutral. The React dashboard derives all agent state (status, event counts, timing) from the event stream.
Standalone Installation