Claude Code Agent Monitor: Real-Time Agent Dashboard
hoangsonww/Claude-Code-Agent-Monitor
Claude Code Agent Monitor is a self-hosted dashboard for watching Claude Code and Codex agent sessions live instead of scrolling terminal output. Reach for it if you run multi-agent or subagent-heavy workflows and want to see what each session did, tool by tool, with cost attached. Skip it if you run Claude Code solo in one terminal — the Kanban boards and workflow DAGs solve a coordination problem you don't have yet.
The Challenge of Tracking AI Agents
Claude Code's own hook system only reports what the main agent does. When a subagent reads a file, runs a shell command, or edits code, that activity lives solely in a per-subagent JSONL transcript that never fires a hook. Once you're running multi-agent workflows or a Task-spawned fleet, an entire layer of activity — and its cost — stays invisible unless you dig through the raw JSONL by hand. Claude Code Agent Monitor exists to reconstruct exactly that layer: it parses each subagent transcript, pairs tool_use blocks with their tool_result by tool_use_id, and rebuilds the parent-child hierarchy so nested subagent activity shows up in the same dashboard as the main session.
Introducing the Claude Agent Dashboard
Claude Code Agent Monitor is a real-time monitoring dashboard for Claude Code and Codex, built on Node.js, Express, React, and SQLite. It hooks into both tools' native hook systems to auto-discover sessions and agents, then streams every event to a React UI over WebSockets with no polling involved. It also ships a local MCP server plus Claude Code and Codex plugins for interacting with the dashboard from inside an agent session.
Core Monitoring Capabilities
- ✓Kanban boards for both agents (Working / Waiting / Completed / Error) and sessions (Active / Waiting / Completed / Error / Abandoned), with a hover tooltip on Waiting badges explaining the awaiting_reason — Needs input, Turn done, At prompt, or Interrupted
- ✓A Health tab with a composite score ring computed as 0.4 x success rate + 0.25 x cache hit rate + 0.25 x (100 minus error rate) + 0.1 x (100 minus heap %), auto-refreshing every 5 seconds
- ✓Cost tracking with time-limited introductory pricing (intro_* fields plus an intro_until cutoff date) so a launch promo like Claude Sonnet 5's discount through 2026-08-31 prices correctly before and after the cutoff, plus per-subagent cost cards separate from the session total
- ✓Subagent tool attribution: on every SubagentStop event it scans each subagent's JSONL file, pairs tool_use with tool_result by tool_use_id, and reconstructs the true parent chain via reconcileSubagentParents — including subagents that spawn their own subagents
- ✓A Workflows page with agent orchestration DAGs, tool-execution Sankey diagrams, collaboration networks, and Workflow Runs reconstructed from on-disk run journals for the Workflow tool
- ✓Remote Data Sources: acquire Claude Code and Codex activity from other machines via SSH, featuring independent remote home paths per provider, synchronization (manual or background-poller), and per-session source badges.
- ✓A rules-based alerting engine (event pattern, inactivity, stuck agent, token threshold) with 14 first-class webhook providers — including Slack, Discord, PagerDuty, Opsgenie, and n8n — plus a generic JSON endpoint with optional HMAC signing
- ✓Built-in locale switching across five UI languages (en, zh, vi, ko, es) via i18next, with the chosen language persisted in browser storage
Practical Uses for Agent Monitoring
- •Debugging a stuck multi-agent run: the Kanban Waiting column plus its hover tooltip tells you whether a session needs input, just finished a turn, or got interrupted, instead of you tailing raw terminal output
- •Watching per-model spend across sessions, where the per-subagent cost cards catch a subagent quietly burning tokens inside a larger run that the session-total number alone would hide
- •Auditing exactly what a subagent touched, using the Session Detail agent hierarchy tree and tool-aware renderers (a diff view for Edit, a terminal view for Bash) instead of grepping JSONL by hand
- •Launching Claude Code or Codex from the Run Agent page itself and leaving it working in the background to reattach later
- •Routing agent alerts into existing on-call tooling — the rules-based alerting engine forwards event-pattern, inactivity, stuck-agent, or token-threshold triggers to Slack, PagerDuty, Opsgenie, or a generic webhook
Setting Up Your Agent Monitor
The material available here documents one concrete setup command: npm run setup, which — among other things — triggers a full historical backfill import of subagent JSONL data on startup. A complete, step-by-step install sequence (cloning, environment configuration, which port the server listens on, how hooks get registered with Claude Code and Codex) is not clearly documented in what's provided. Given the stack — Node.js, Express, React/Vite, SQLite — expect a clone-and-npm-install setup with a native hook-registration step, but that's an inference, not a documented fact.
Strengths
- ✓Reconstructs subagent activity that Claude Code's own hooks never surface, including nested subagents-of-subagents via reconcileSubagentParents
- ✓Handles time-limited promo pricing (an intro rate up to a cutoff date, standard rate after) without a code change when a new model promo lands — it's an editable Settings field
- ✓WebSocket push means the UI updates the instant a hook fires rather than on a polling interval
- ✓Remote Data Sources lets one dashboard instance watch Claude Code and Codex activity on other machines over SSH instead of running a separate instance per machine
- ✓Alerting ships with 14 named webhook providers plus a generic HMAC-signed JSON endpoint, so it plugs into whatever on-call tooling a team already runs
Current Scope and Considerations
- △The available documentation doesn't spell out the install/deploy sequence in detail — only npm run setup is named, so first-time setup means reading the actual repo rather than following a documented walkthrough
- △It only sees activity that lands under the standard Claude Code and Codex transcript paths (~/.claude, ~/.codex/sessions) — Cursor sessions get picked up incidentally because Cursor happens to write into the same paths, and the dashboard can't tell Cursor and Claude Code apart, worth knowing before trusting a session's attribution at face value on a mixed-tool machine
- △At 877 stars and 198 forks, the community and third-party guides around it are thinner than for a widely adopted hosted observability platform
- △Cost figures come from configurable pricing rules, not a reconciled billing statement — accuracy depends on keeping the Model Pricing settings current yourself
Other AI Agent Observability Tools
Who Benefits from This Dashboard?
Claude Code Agent Monitor fits a developer or small team already running multi-agent or subagent-heavy workflows in Claude Code or Codex — Task-tool fleets, workflow DAGs, background agents — who want a live picture of what's running, what it's costing, and where it's stuck, without tailing raw JSONL. It's less useful if you run Claude Code interactively, one session at a time, with no subagents: the Kanban boards, workflow Sankey diagrams, and subagent hierarchy tree are solving a coordination problem you don't have yet. Self-hosting a Node.js/Express/SQLite service is table stakes here too, so it suits someone comfortable running a small local service rather than someone who wants a hosted SaaS dashboard.
Common Questions
Claude Code Agent Monitor tracks sessions, agent and subagent activity, tool calls, token usage, per-model cost, compactions, API errors, and turn durations, all extracted in real time from Claude Code and Codex transcripts.
Claude Code Agent Monitor is built with Node.js, Express, React, Vite, TailwindCSS, SQLite, and WebSockets, written in TypeScript, with a local MCP server for scripting dashboard operations.
Yes. Claude Code Agent Monitor pushes updates over WebSockets instead of polling, so the UI reflects new events the moment a hook fires; Health-tab metrics also auto-refresh every 5 seconds.
Yes. The Remote Data Sources settings in Claude Code Agent Monitor extract Claude Code and Codex activity from remote systems via SSH, with manual or background-poller syncing and per-session source badges.
Claude Code Agent Monitor is released under the MIT license.
Claude Code Agent Monitor prices token usage against configurable per-model pricing rules, including time-limited introductory rates that apply before a set cutoff date and standard rates after, with subagent cards showing each subagent's own cost separately from the session total.