Show HN: Real-time dashboard for Claude Code agent teams

TL;DR Highlight

An open-source real-time monitoring dashboard that solves the visibility problem when Claude Code runs multiple sub-agents in parallel. Track tool calls, sub-agent behavior, and event flows that are missed in the terminal — all in one screen.

Who Should Read

Developers running Claude Code with multiple agents in parallel or operating complex multi-agent workflows. A perfect fit when you want to understand what's happening in real time rather than digging through post-mortem logs after an agent fails.

Core Mechanics

When Claude Code autonomously spawns sub-agents and makes tool calls, the terminal only shows a fraction of the total activity. Sub-agents operate essentially invisibly, and when something goes wrong three levels deep, the only option was to sift through logs after the fact — this project solves that problem.
Instead of OTEL (OpenTelemetry, the distributed tracing standard framework), it uses Claude Code's hook system to capture events. Hooks provide a complete picture of agent behavior and record tool call sequences and their contents as-is.
Installation is straightforward: `claude plugin marketplace add simple10/agents-observe` → `claude plugin install agents-observe` → restart Claude Code. From the next session onward, a Docker container starts automatically and the dashboard is available at http://localhost:4981. Docker and Node.js are prerequisites.
To minimize the performance impact of hooks, the implementation uses a background async approach instead of blocking (synchronous) execution. In environments where agents make dozens of tool calls per minute, even 100ms of blocking per hook adds 2–3 seconds to the overall task, and this multiplies with more parallel agents.
Both local and remote setups are supported. Running the server and dashboard on a remote VM allows multiple Claude Code instances to send events to the same server, enabling monitoring of an entire multi-agent team from a single place.
The dashboard includes powerful filtering, search, and multi-agent session visualization. You can review which tools each agent called and in what order via a timeline view, allowing you to reconstruct 'how the agent arrived at this conclusion' after the fact.
Two slash commands are provided — /observe and /observe status — to open the dashboard URL or check server status directly within a Claude Code session.

Evidence

"A user running multiple Claude Code agents in parallel on a remote VM shared firsthand experience that 'throughput drops sharply when hooks block on the agent critical path.' With agents making dozens of tool calls per minute, hundreds of milliseconds accumulating per hook is very noticeable. They assessed the Docker-based service pattern as the right trade-off for achieving observability without adding overhead to the agents themselves. Multiple people raised the transparency issue that 'there's no way to know whether an agent's self-report matches actual outcomes' in multi-agent operations. When a coordinator spawns builder, reviewer, and tester agents in parallel, the results each agent reports may be 'sanitised optimism,' and it was noted that event stream logs cannot verify whether results are actually correct. A question was raised about concurrency handling when multiple agent teams write to the same JSONL file simultaneously — no concrete answer regarding log file conflict handling in parallel agent environments was confirmed in the thread. There were also surprised reactions to Claude Code usage costs, with comments like 'are you spending hundreds to thousands of dollars a day on Claude tokens?' — suggesting that heavy users running multiple agents in parallel for extended periods are the primary target audience. There were also realistic comments that average developers hit usage limits quickly. Someone asked whether the dashboard tracks the full tree or only one level when sub-agents spawn their own sub-agents (a tree structure) — an important edge case in real production environments — but no clear answer was confirmed in the thread."

How to Apply

"If you're running multiple agents in parallel with Claude Code and struggle to identify the cause when something goes wrong, install with `claude plugin install agents-observe` and monitor tool call flows in real time at the localhost:4981 dashboard — pinpoint the problem immediately without post-mortem log analysis. If you're operating a Claude Code agent team on a remote VM, bring up the server with Docker Compose and configure multiple instances to send events to the same endpoint to observe distributed agents from a single dashboard. `docker-compose.yml` is already included. If you're skeptical about the reliability of an agent's output, trace the actual path through the event timeline — what files the agent read and what commands it executed — to uncover discrepancies between 'self-reported' behavior and actual actions. If you've tried building your own hook-based monitoring system but abandoned it due to performance issues, reference this project's background async hook pattern to redesign your system so it doesn't block the agent critical path."

Code Example

snippet

# Installation
claude plugin marketplace add simple10/agents-observe
claude plugin install agents-observe
# After restarting Claude Code, the Docker container starts automatically
# Dashboard: http://localhost:4981

# Slash commands available within a Claude Code session
/observe          # Open dashboard URL + check server status
/observe status   # Server health check and URL display

# Run directly with Docker Compose
docker-compose up -d

Terminology

HookA script that runs automatically when a specific event occurs in Claude Code (such as a tool call or file read). It can intercept agent behavior for logging or additional processing.

OTELShort for OpenTelemetry. A standardized observability framework for collecting logs, metrics, and traces in distributed systems. This project captures more granular events by using Claude-specific hooks instead of OTEL.

SubagentA subordinate agent created by the main agent (coordinator) to distribute work. Each sub-agent independently makes tool calls and performs tasks, but by default this activity is invisible to the parent agent.

ObservabilityThe ability to understand what is happening inside a system from the outside. It's about making agents that behave like black boxes transparent — like looking through glass.

JSONLShort for JSON Lines. A text file format where each line is an independent JSON object. Well-suited for appending logs or event streams line by line.

Critical PathThe processing path that directly affects the total time to complete a task. If blocking occurs here, the entire process slows down no matter how fast other tasks run.