Claude Code Agent Monitor

System Overview

📡 Live dashboard — real-time agent cards, stats, and activity feed

Claude Code Agent Monitor integrates with Claude Code through its native hook system. When Claude Code performs any action — tool use, session start, subagent orchestration, session end — it fires a hook that calls a small Node.js script bundled with this project. That script forwards the event over HTTP to the dashboard server, which stores it in SQLite and broadcasts it to the browser over WebSocket.

What's Included

Every feature is driven by real hook events — nothing is hardcoded or simulated in production mode.

Screenshots

📋 Sessions table — searchable, filterable, paginated

🔬 Session detail — agent tree and event timeline

📂 Kanban board — 5-column agent status view

📰 Activity feed — real-time streaming event log

📊 Analytics — token usage, tool frequency, and trends

🔀 Workflows — agent DAGs and tool Sankey diagrams

GitHub Star History

This chart tracks how interest in Claude Code Agent Monitor has grown over time. The curve keeps climbing as more developers discover the project, share it, and use it in real workflows. Each new star is a small vote of confidence from the community.

⭐ Enjoying the project? Give it a star on GitHub and help more builders discover it.

Hook Events Captured

Quick Start

# 1. Clone
git clone https://github.com/hoangsonww/Claude-Code-Agent-Monitor.git
cd Claude-Code-Agent-Monitor

# 2. Install all dependencies (server + client)
npm run setup

# 3. Start in development mode
npm run dev
# → Express server on http://localhost:4820
# → Vite dev server on http://localhost:5173

# 4. (Optional) Build and run the local MCP server
npm run mcp:install
npm run mcp:build
npm run mcp:start              # stdio (for MCP host integration)
npm run mcp:start:http         # HTTP + SSE server on port 8819
npm run mcp:start:repl         # interactive CLI with tab completion

# 5. Open the dashboard
# http://localhost:5173  (dev)
# http://localhost:4820  (prod after npm run build && npm start)

Alternative: Docker / Podman

A multi-stage Dockerfile and docker-compose.yml are included. You can run the monitor with either Docker or Podman and keep the SQLite database in a named volume.

# Docker Compose
docker compose up -d --build

# Podman Compose
CLAUDE_HOME="$HOME/.claude" podman compose up -d --build

# Plain Docker / Podman
docker build -t agent-monitor .
docker run -d --name agent-monitor \
  -p 4820:4820 \
  -v "$HOME/.claude:/root/.claude:ro" \
  -v agent-monitor-data:/app/data \
  agent-monitor

Optional: Enable MCP and Agent Extensions

This repository also ships a local MCP server under mcp/ and extension scaffolding for both Claude Code and Codex. These are optional for the dashboard UI, but recommended for complete local-agent workflows. The MCP server supports stdio (for host integration), HTTP+SSE (for remote clients), and an interactive REPL (for operator debugging).

# MCP lifecycle
npm run mcp:install
npm run mcp:build
npm run mcp:start              # stdio (default — for MCP hosts)
npm run mcp:start:http         # HTTP + SSE server on port 8819
npm run mcp:start:repl         # interactive CLI with tab completion

Verification

After starting a Claude Code session, you should see:

Configuration

Environment Variables

Hook Configuration

The server writes the following to ~/.claude/settings.json on every startup:

{
  "hooks": {
    "SessionStart": [
      { "hooks": [{ "type": "command", "command": "node \"/path/to/scripts/hook-handler.js\" SessionStart" }] }
    ],
    "PreToolUse": [
      { "matcher": "*", "hooks": [{ "type": "command", "command": "node \"/path/to/scripts/hook-handler.js\" PreToolUse" }] }
    ],
    "PostToolUse": [
      { "matcher": "*", "hooks": [{ "type": "command", "command": "node \"/path/to/scripts/hook-handler.js\" PostToolUse" }] }
    ],
    "Stop":         [{ "matcher": "*", "hooks": [{ "type": "command", "command": "node \"/path/to/scripts/hook-handler.js\" Stop" }] }],
    "SubagentStop": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "node \"/path/to/scripts/hook-handler.js\" SubagentStop" }] }],
    "Notification": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "node \"/path/to/scripts/hook-handler.js\" Notification" }] }],
    "SessionEnd": [
      { "hooks": [{ "type": "command", "command": "node \"/path/to/scripts/hook-handler.js\" SessionEnd" }] }
    ]
  }
}

Existing hooks are preserved. The installer only adds or updates entries containing hook-handler.js.

Scripts Reference

System Architecture

Core dashboard telemetry is composed of three processes (Claude hook source, dashboard server, browser UI). When the local MCP sidecar is enabled, it integrates with the same dashboard API via stdio, HTTP+SSE, or interactive REPL transport.

Agent State Machine

Session State Machine

Data Flow

Event Ingestion Pipeline

Client Data Loading Pattern

Server Architecture

Server Modules

Client Architecture

Client Routes

Key Client Modules

State Management

The client deliberately avoids Redux / Zustand / Context. Each page owns its data and lifecycle. WebSocket events trigger a reload or append — no complex state merging.

Database Design

Indexes

SQLite Configuration

API Reference

All endpoints return JSON. Errors follow { "error": { "code", "message" } }.

Health

Sessions

Agents

Events, Stats, Analytics

Hooks Ingestion

Pricing

Settings

Workflows

{
  "hook_type": "PreToolUse",
  "data": {
    "session_id": "abc-123",
    "tool_name":  "Bash",
    "tool_input": { "command": "ls -la" }
  }
}

WebSocket Protocol

Message Envelope

// All messages use this shape
{
  type:      "session_created" | "session_updated" |
             "agent_created"   | "agent_updated"   | "new_event";
  data:      Session | Agent | DashboardEvent;
  timestamp: string;  // ISO 8601
}

Hook Integration

Hook Handler Design

scripts/hook-handler.js is a minimal, fail-safe forwarder. It always exits 0 so it can never block Claude Code regardless of server state.

Hook Installation Flow

MCP & Agent Extensions

In addition to dashboard telemetry, this project includes a production-grade local MCP server and complete extension scaffolding for both Claude Code and Codex. This gives agents a richer local tool surface while keeping all execution local-first. The MCP server supports three transport modes: stdio for host integration, HTTP+SSE for remote clients, and an interactive REPL for operator debugging.

🔧 MCP Server REPL — interactive tool invocation with colored output

Local MCP Server Runtime

The mcp/ package exposes dashboard-oriented tools for AI agents across three transport modes. Mutation and destructive operations are policy-gated by environment variables and disabled by default. HTTP mode serves both Streamable HTTP (protocol 2025-11-25) and legacy SSE (protocol 2024-11-05). REPL mode provides tab-completed interactive tool invocation with colored output and JSON syntax highlighting.

Agent Extension Layout

Root Helper Scripts

Plugin Marketplace

The Agent Monitor ships with an official Claude Code plugin marketplace containing five production-ready plugins. These extend Claude Code with skills, agents, hooks, CLI tools, and MCP integration — all grounded in the real data model (token tracking with compaction baselines, cost calculation via pattern-matched pricing rules, workflow intelligence with 11 datasets per session, and session metadata including thinking blocks, turn counts, and inference geography).

Installation

# Add the marketplace
claude plugin marketplace add hoangsonww/Claude-Code-Agent-Monitor

# Install individual plugins
claude plugin install ccam-analytics@hoangsonww-claude-code-agent-monitor
claude plugin install ccam-productivity@hoangsonww-claude-code-agent-monitor
claude plugin install ccam-devtools@hoangsonww-claude-code-agent-monitor
claude plugin install ccam-insights@hoangsonww-claude-code-agent-monitor
claude plugin install ccam-dashboard@hoangsonww-claude-code-agent-monitor

Available Plugins

Skill Usage Examples

# Analytics — session report with per-model token breakdown + cost
/ccam-analytics:session-report latest

# Analytics — cost breakdown with cache efficiency analysis
/ccam-analytics:cost-breakdown this week

# Productivity — daily standup grouped by project
/ccam-productivity:daily-standup today

# Productivity — workflow optimization using workflow intelligence API
/ccam-productivity:workflow-optimizer analyze

# DevTools — debug a session's full event chain
/ccam-devtools:session-debug errors

# Insights — detect tool flow patterns and anti-patterns
/ccam-insights:pattern-detect tools

# Dashboard — one-line metrics summary
/ccam-dashboard:quick-stats

CLI Tools

# Quick terminal dashboard
ccam-stats                  # Sessions, costs (per-model), tokens (with baselines)
ccam-stats --cost           # Cost summary with matched pricing rules
ccam-stats --tokens         # Token usage including compaction baselines
ccam-stats --json           # Raw JSON output

# System diagnostics
ccam-doctor                 # Full diagnostic: API, endpoints, database, hooks, freshness
ccam-doctor --quick         # Basic connectivity check

# Data export
ccam-export sessions --format csv --limit 500
ccam-export all --output backup.json

Plugin Architecture

Each plugin follows the official Claude Code plugin specification. The marketplace manifest at .claude-plugin/marketplace.json catalogs all five plugins. Each plugin directory contains:

plugins/ccam-{name}/
├── .claude-plugin/plugin.json    # Plugin manifest (name, version, description)
├── skills/{skill-name}/SKILL.md  # Skill definitions with $ARGUMENTS
├── agents/{agent-name}.md        # Agent definitions (model, tools, instructions)
├── hooks/hooks.json              # Event hooks (fail-safe, non-blocking)
├── bin/{cli-tool}                # CLI scripts (added to PATH)
├── .mcp.json                     # MCP server configuration (dashboard plugin)
└── settings.json                 # Plugin settings (dashboard plugin)

Data Model Reference

All plugins query the Agent Monitor API at http://localhost:4820. Key capabilities they leverage:

📖 Full documentation: docs/plugins.md

Statusline Utility

🖥️ Statusline — context window, tokens, git branch at a glance

The statusline/ directory contains a standalone CLI statusline for Claude Code — completely independent of the web dashboard. It renders a color-coded bar at the bottom of the Claude Code terminal showing context window usage, token counts, and git branch.

Sonnet 4.6 | nguyens6 | ~/agent-dashboard/client | main | ████████░░ 79% | 3↑ 2↓ 156586c

Installation

Add this to ~/.claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "bash \"/absolute/path/to/statusline/statusline-command.sh\""
  }
}

Settings Page

⚙️ Settings — pricing, hooks, data management, and system info

The /settings route provides a comprehensive management interface with six sections:

Deployment Modes

Container Runtime (Docker / Podman)

The production image is OCI-compatible and works with both Docker and Podman. The server listens on 4820, reads legacy Claude history from a read-only mount, and persists SQLite data under /app/data.

# Docker Compose
docker compose up -d --build

# Podman Compose
CLAUDE_HOME="$HOME/.claude" podman compose up -d --build

# Stop the stack
docker compose down
# or
podman compose down

Docker / Podman

A multi-stage Dockerfile and docker-compose.yml are included. Both Docker and Podman are fully supported — the image is OCI-compliant.

Quick Start

# Docker Compose
docker compose up -d --build

# Podman Compose
CLAUDE_HOME="$HOME/.claude" podman compose up -d --build

Plain Docker / Podman (no Compose)

# Build the image
docker build -t agent-monitor .
# — or —
podman build -t agent-monitor .

# Run the container
docker run -d --name agent-monitor \
  -p 4820:4820 \
  -v "$HOME/.claude:/root/.claude:ro" \
  -v agent-monitor-data:/app/data \
  agent-monitor

Volume Mounts

Multi-Stage Build

The Dockerfile uses three stages to minimize the final image size:

Performance Characteristics

Security Considerations

Troubleshooting

No sessions appearing after starting Claude Code

Check 1 — Is the server running?

curl http://localhost:4820/api/health
# Expected: {"status":"ok","timestamp":"..."}

Check 2 — Are hooks installed?

# Open ~/.claude/settings.json and confirm it contains "hook-handler.js"
# If not, re-run:
npm run install-hooks

Check 3 — Start a new Claude Code session

Hooks only apply to sessions started after installation. Restart Claude Code after starting the dashboard.

Check 4 — Is Node.js in PATH?

On some systems the shell environment when Claude Code fires hooks may not include the full PATH. Test with node --version. If not found, use the absolute path to node in the hook command.

Common Issues

Technology Choices