Agent Dashboard for Claude Code

Agent Dashboard for Claude Code: A Real-Time Monitoring Platform for AI Agent Activity

Introduction In the rapidly evolving world of AI assistants, visibility into how Claude Code agents behave is everything. The Agent Dashboard for Claude Code is a real-time monitoring platform designed to track, visualize, and analyze Claude Code agent sessions, tool usage, and subagent orchestration as it happens. Built on a modern stack—including Node.js, Express, React, and SQLite—the dashboard integrates directly with Claude Code through its native hook system, enabling seamless session tracking, analytics, and workflow intelligence. The result is a sleek, dark-themed interface that gives operators a comprehensive, at-a-glance understanding of how agents perform, where they spend tokens, and how subagents collaborate to accomplish complex tasks.

Overview

A Real-Time, End-to-End View The dashboard provides end-to-end visibility into Claude Code activity. You can monitor sessions, observe live events, track which tools are invoked, and understand how subagents are orchestrated within larger workflows. Real-time WebSocket broadcasts replace the need for polling, so updates appear instantly as events occur. The architecture maps a clear data path: Claude Code fires hooks on tool use and other lifecycle moments, the Hook Handler relays events to the Dashboard Server, the server persists data in SQLite, and the UI renders live updates in your browser.

Direct Hook-Based Integration The system is engineered to plug directly into Claude Code via its native hook system. This tight integration ensures that every interesting moment—the start of a session, a tool invocation, a prompt waiting state, subagent activity, and session completion—flows into the dashboard with fidelity. A local MCP server layer lives alongside to expose a catalog of tools for introspection and dashboard management, enabling Claude Code workflows to interact with the dashboard programmatically.

Visual Reference Gallery The UI presents a cohesive suite of views designed to illuminate different facets of agent activity. The dashboard, Kanban boards, sessions lists, activity feed, analytics, and workflows come together in a consistent, responsive design.

• Dashboard overview and active agent cards
• Kanban Board views for Agents and Sessions
• Detailed Sessions list with search, filters, and server pagination
• Session Detail pages featuring Agents, Timeline, and Conversation tabs
• Live Activity Feed with real-time event streaming
• Analytics: token usage, tool frequency, heatmaps, and trends
• Workflows: agent orchestration diagrams and pattern detection
• Settings for pricing, hooks, data export, and system information

Images from the Input

• Dashboard Overview:
• Kanban Board (agents):
• Kanban Board (sessions):
• Sessions Overview:
• Session Detail – Agents:
• Session Detail – Conversation:
• Session Detail – Timeline:
• Activity Feed Overview:
• Analytics Overview:
• Workflows Overview:
• Settings Overview:
• Swagger UI:
• Import History UI:
• MCP REPL:
• Update modal:
• VS Code Extension:
• Statusline Demo:

Internationalization (i18n)

Global Reach with Localized Interfaces The UI ships with built-in locale switching for English (en), Chinese (zh), and Vietnamese (vi). Language resources are loaded by namespace and persisted in the browser’s storage, ensuring a stable user experience across refreshes and sessions. The i18n flow starts with the user selecting a language, passes through the i18next detector (localStorage and navigator), resolves to a fallback of English when needed, and then loads the appropriate namespace resources for UI rendering and accessibility labels.

• Language switch is accessible from the dashboard and persists across reloads.
• The architecture supports an end-to-end translation experience, including tooltips and dynamic labels.
• Documentation points to dedicated i18n guidance for a full architectural view.

User Interface: A Dark-Themed, Responsive Experience

A cohesive, modern design that scales from mobile to desktop, the UI offers intuitive navigation and rich visualizations to explore agent activity in depth.

• Sidebar navigation gives quick access to Dashboard, Kanban Board, Sessions, Activity Feed, Analytics, Workflows, and Settings.
• Each page is designed to surface deep insights with real-time updates and rich visualizations.
• The interface emphasizes clarity: status indicators, tool usage bars, token flows, and subagent hierarchies are presented in digestible, interactive components.

Key UI components and features include:

• Dashboard: a high-level view of metrics, active agent cards, and a real-time activity feed.
• Kanban Board: two perspectives—Agents and Sessions—with four and five columns respectively. The Waiting column surfaces human-involved pauses (prompts, permissions, or fresh prompts). Cards show model, cost, and current tool.
• Sessions: a searchable, filterable, server-paginated table of all sessions, with per-session cost and metadata.
• Session Detail: a comprehensive per-session panel featuring an active-agent banner, six counters (events, tool calls, subagents, compactions, errors, duration), top-tool usage, subagent type distribution, token-flow visualizations, and a hierarchical agent tree. The Conversation tab renders transcripts with markdown, syntax-highlighted code blocks, and per-tool callouts.
• Timeline: a chronological event timeline with multi-dimension filters, pre/post grouping by tooluseid, and tool-aware payload renderers.
• Activity Feed: real-time event log with pause/resume, grouping, and multi-dimension filters; includes a jump-to-session feature per row.
• Analytics: token usage by model, tool frequency, activity heatmaps, and live/offline indicators.
• Workflows: deep-dive diagrams (DAGs, Sankey diagrams, collaboration networks) and 11 interactive sections of workflow intelligence, each with rich, i18n-aware tooltips and narrative explanations.
• Settings: pricing rules, hook installation status, data management, and notification preferences.

A Visual Timeline of the UI The gallery of visuals above showcases how the UI behaves and what you can expect during live operation. The dashboards respond in real time to hook events, and visualizations reveal relationships such as which tools are most used, how subagents branch out, and how token flows evolve over the lifetime of a session.

Features and Capabilities: A Rich Suite

To give you a sense of the breadth and depth, here are the core capabilities translated into practical terms, with the emphasis on how they help you understand Claude Code activity.

• Real-time monitoring: WebSocket-based updates push changes to the UI instantly, avoiding polling latency.
• Session-centric view: each session aggregates agent activity, tool usage, costs, and timeline events for quick triage.
• Agent and subagent visibility: a hierarchical, collapsible tree shows parent-child relationships, with expand/collapse controls and clear indicators for leaf nodes.
• Tool and payload insights: per-tool renderers present tool input/output, token usage, and results in an accessible, readable format.
• Transcript and conversation rendering: live transcripts support markdown, with syntax-highlighted code blocks and per-tool styling to distinguish tool calls from user prompts.
• Detailed event timelines: pre/post groupings and multi-dimension filters enable precise analysis of tool usage sequences and event correlations.
• Cost awareness: token baselines, per-model pricing, and compaction-aware accounting ensure transparent cost tracking.
• Subagent orchestration: Sankey diagrams, DAGs, and networks illustrate how subagents collaborate across workflows, including detours and handoffs.
• Import history and data integration: the dashboard can ingest legacy JSONL transcripts and subagent data, preserving baselines and enabling seamless backfill.
• MCP integration: a local MCP server exposes tools for introspection and dashboard operations, enabling deeper automation within Claude Code workflows.
• Notifications and updates: browser push notifications keep you informed about critical events, even when the dashboard tab is not active.
• Internationalization: multilingual UI with consistent translations across charts, tooltips, and narrative explanations.
• Seed data and hosting options: built-in seeds for demos and flexible deployment options, including Docker, Podman, and cloud deployment tooling.

Getting Started: Quick Start Guide

Prerequisites

• Node.js 18.0.0 or newer (22+ recommended)
• npm 9.0.0 or newer

Step-by-step Setup

• Clone the repository and set up dependencies:
• git clone https://github.com/hoangsonww/Claude-Code-Agent-Monitor.git
• cd Claude-Code-Agent-Monitor
• npm run setup
• Configure Claude Code Hooks:
• npm run install-hooks This updates your ~/.claude/settings.json so Claude Code events are forwarded to the dashboard.
• Run in development or production modes:
• Development (hot reload on both server and client):
  • npm run dev
• Production (single process, built client):
  • npm run build && npm start

Optional: Makefile shortcut If you have Make installed, you can use make to run targets such as make dev or make build. The project provides a Makefile with helpful shortcuts for common tasks.

Optional: Local MCP server To explore the MCP sidecar for local tool access:

• npm run mcp:install
• npm run mcp:build
• npm run mcp:start You can start in stdio mode (default), HTTP + SSE, or an interactive REPL depending on your integration scenario.

Optional: Seed data

• npm run seed This creates a small set of sample sessions, agents, and events to explore the UI immediately.

Optional: Docker / Podman You can run the dashboard with Docker or Podman, including a Compose setup. The repository includes a Dockerfile and docker-compose.yml to help you deploy quickly.

Optional: VS Code Extension There is an official Claude Code Agent Monitor VS Code extension that provides a live sidebar, analytics, and a native webview dashboard. See the VS Code extension directory for details and installation steps.

How It Works: Architecture and Data Flow

A Clear Data Cycle

• Claude Code hooks emit events: The Claude Code client triggers events such as SessionStart, PreToolUse, PostToolUse, Stop, SubagentStop, and SessionEnd.
• Hook Handler: A lightweight process reads events from standard input and forwards them via HTTP POST to the dashboard API.
• Server processing: The Express server with SQLite persists state, auto-creates sessions and agents, and updates real-time metrics.
• WebSocket broadcasting: After transactional writes, the server broadcasts changes to all connected clients via WebSocket.
• UI rendering: The React-based frontend re-renders affected components, reflecting new events, tool calls, and session states in real time.

Hook lifecycle and agent state

• SessionStart creates a session and the main agent, stamping an awaitinginputsince flag so fresh sessions land in a Waiting state.
• UserPromptSubmit clears waiting state and marks the main agent as working, the primary signal that a turn has begun.
• PreToolUse clears waiting and marks the agent as working; creating subagents when the tool invoked is Agent.
• PostToolUse clears the current_tool and may leave the agent in a working state through the duration of tool runs.
• Stop marks the main agent as idle, re-stamping the waiting flag if no error occurred; background subagents may continue running.
• SubagentStop completes subagents and triggers a scan pass to import and correlate subagent tool uses with their results.
• Notification hook events can trigger browser notifications (e.g., permission prompts, new sessions, or subagent spawns).

Session and event lifecycles

• Activity and sessions are tracked with lifecycle states such as active, completed, error, and abandoned.
• Waiting state is a UI overlay derived from awaitinginputsince, not a persisted status—this keeps the actual progress state clean and predictable.
• A periodic sweep detects abandoned sessions and backfills missing activity to keep the dashboard current and coherent.

Cost and analytics

• Token usage per model is calculated against configurable pricing rules; costs are updated retroactively once pricing rules are set.
• The system accounts for compactions, preserving token totals to avoid double-counting when context windows shrink.

Data storage and schema

• Engine: SQLite 3 (with an optional better-sqlite3 backend).
• Location: data/dashboard.db
• Journal mode: WAL to allow concurrent reads during writes
• Key entities: sessions, agents, events, tokenusage, modelpricing
• The ER diagram shows relationships such as sessions having many agents, events linked to sessions and agents, and token usage tied to sessions/models.

API and WebSocket: Access and Realtime

REST API The dashboard exposes a comprehensive REST API for sessions, agents, events, analytics, pricing, workflows, settings, and import history. Endpoints support filtering, pagination, and detailed drill-down. For example:

• GET /api/sessions to list sessions with optional status and query filters
• GET /api/sessions/:id for a detailed session
• GET /api/sessions/:id/transcripts for transcript data
• GET /api/agents to list agents with various filters
• GET /api/events to list events
• GET /api/workflows for orchestration and pattern data
• GET /api/settings/info for system health and configuration

WebSocket

• WebSocket endpoint: ws://localhost:4820/ws
• Message types include sessionupdated, agentupdated, newevent, and sessioncreated, enabling instant UI refresh without polling.

Hook events: The heartbeat of the dashboard

• SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SubagentStop, Notification, SessionEnd, Compaction, APIError, TurnDuration, ToolError
• Each event maps to a corresponding UI update and the appropriate augmentation of the internal state (e.g., creating subagents, updating current_tool, or recording error events).

Browser notifications

• Web Push (VAPID) supports critical alerts even when the dashboard tab is not active.
• The notification system is configurable per event, with a master toggle in settings.
• macOS audio support is explicitly configured to ensure audible alerts on supported systems.

Update Notifier: Up-to-date awareness without auto-updating itself The dashboard periodically checks for upstream changes and surfaces a modal with a one-click command to pull updates and re-run the setup, while avoiding auto-updates that could disrupt running sessions. This keeps your dev, test, and production environments stable regardless of how you deploy.

• The update modal includes the exact command: git pull && npm run setup
• The update badge on the sidebar shows behind-ahead status for quick visibility
• The UI provides a copy-to-clipboard button for ease of use

VS Code Extension

A dedicated Claude Code Agent Monitor VS Code extension exists to bring dashboard visibility into the editor. Features include:

• Live Sidebar: Real-time agent health and activity
• Usage Analytics: Tokens, costs, and event counts
• Status Bar integration for quick health checks
• Deep navigation to dashboard views and recent sessions
• A native webview to view the dashboard from within VS Code

Images and UI glimpses accompany the extension overview and usage.

Data Storage and Project Structure

SQLite as the storage engine

• Engine: SQLite 3 (via better-sqlite3 or node:sqlite as fallback)
• Location: data/dashboard.db
• WAL mode supports concurrent reads during writes
• Data reset by removing data/dashboard.db

ER Diagram

• The data model includes sessions, agents, events, tokenusage, and modelpricing, with defined relationships that reflect the real-world usage of Claude Code agents and their interactions.

MCP Integration and Safety

MCP Transport Modes

• stdio (default): JSON-RPC over stdin/stdout
• HTTP + SSE: Streamable HTTP for remote clients
• REPL: Interactive CLI for testing and debugging

MCP Tool Surface

• Observability, Sessions, Agents, Events, Pricing, and Maintenance surfaces
• Safety models control mutation and destructive actions via a structured permission gate

MCP Safety Model

• A layered permission model ensures that destructive actions require explicit assurance steps
• The approval tokens and mutation gates protect data integrity

Cloud Deployment and Observability

Deployment methods

• Helm, Kustomize, and Terraform for cloud provisioning and management
• Release strategies include rolling updates, blue-green, and canary deployments

Observability

• Prometheus and Grafana for metrics, alerting, and visualization
• Coralogix for logs and end-to-end observability
• OpenTelemetry Collector for traces, metrics, and logs

Project Structure Snapshot

• A comprehensive repository layout includes:
• server: Express API, routing, database, and WebSocket
• client: React app with Vite, Tailwind, and a robust component library
• mcp: local MCP server and tool catalog
• plugins: official Claude Code agent monitor plugins and tooling
• statusline: a CLI statusline utility for quick context at the terminal
• data: the on-disk SQLite database
• deployments: cloud provisioning and deployment tooling

Troubleshooting and Tips

• Hooks not firing: Ensure hooks are installed via npm run install-hooks and that Claude Code points to the host running the hook handler.
• Dashboard shows no data: Verify the server is running (npm run dev) and check health at http://localhost:4820/api/health.
• WebSocket disconnected: The client auto-reconnects; make sure port 4820 is open in your firewall.
• Stale data after restart: Seed data again with npm run seed or reset the database by deleting data/dashboard.db.
• MCP connection issues: Confirm the MCP base URL matches settings and rebuild/start MCP as needed.

Legal and Licensing

License: MIT. The dashboard project is released under MIT, with a permissive license for both personal and commercial use, subject to the license terms included in the repository.

Conclusion

The Agent Dashboard for Claude Code is more than just a pretty UI. It is a full-fledged, real-time observability platform designed to give operators, engineers, and data scientists deep, actionable insight into Claude Code agent behavior. With live session monitoring, granular tool usage analytics, subagent orchestration visuals, and a flexible pipeline that includes an integrated local MCP server and a robust extension ecosystem, you gain a single source of truth for AI workflow intelligence. The careful blend of real-time data flows, i18n readiness, and enterprise-grade features makes this dashboard a powerful companion for anyone working with Claude Code in production or experimentation.

From the real-time heartbeat of hook events to the nuanced narratives of per-session transcripts and tool flows, the dashboard makes it possible to understand not just what happened, but why it happened, and how to improve future interactions. Whether you are monitoring a handful of sessions or orchestrating a complex network of subagents and tools, this dashboard provides clarity, control, and confidence in your Claude Code deployments.