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

📡 Dashboard · Monitor — live overview of active sessions and agents. Stats tiles, collapsible subagent hierarchy cards, and a recent activity feed. Auto-refreshes every 5 s via WebSocket

🩺 Dashboard · Health — composite health score ring, storage engine donut, cache/error/success gauges, tool invocation bars, subagent effectiveness, and model token distribution

📋 Kanban Board (agents) — agents swim-laned by status: Working, Waiting, Completed, Error. Cards show model, cost, and current tool call. Yellow column flags agents waiting on user input

🗂️ Kanban Board (sessions) — sessions swim-laned across 5 columns: Active, Waiting, Completed, Error, Abandoned. Each card shows agent count, duration, model, and cumulative cost

📂 Sessions — searchable, filterable, server-paginated table. Each row shows status badge, agent count, duration, model, and cost. Click any row to drill into session detail

🤖 Session Detail · Agents — overview tiles (events, tool calls, subagents, errors, duration), top-tool usage bars, subagent type breakdown, and a collapsible parent–child agent hierarchy tree

💬 Session Detail · Conversation — full transcript viewer with markdown rendering, syntax-highlighted code blocks, per-tool sections, and collapsible thinking blocks

🔬 Session Detail · Timeline — chronological event timeline with multi-dimension filters, color-coded entries by type, expandable hook payloads, and direct links to the owning session and agent

📰 Activity Feed — real-time streaming event log with pause/resume buffering, multi-dimension filters, expandable hook payloads, color-coded entries, and per-row session navigation buttons

📊 Analytics — token usage by model, tool frequency bars, 52-week activity heatmap, 30-day sparkline trends, session outcome donuts, and cost summary with WebSocket auto-refresh

🔀 Workflows — D3.js agent orchestration DAG, tool-execution Sankey diagram, directed pipeline graph, effectiveness scorecards, concurrency swim-lanes, and complexity bubble charts

🧬 Workflow Runs — "dynamic workflows" spawned by the Workflow tool, reconstructed from on-disk run journals: status, agent count, tokens, and tool calls, expandable into a per-agent breakdown (phase, state, tokens, tools, duration) with humanized result previews

🧬 Workflow Runs · expanded — a run opened up: clickable color-coded phase filters, the per-agent metrics table, and a full list of clickable result items that expand to each agent's complete prompt and result

🧬 Workflow Runs · in a session — the same fleets linked to their launching session, so a session's dynamic-workflow sub-agents and their folded-in token cost are visible inline

🧰 Claude Config Explorer — 12-tab inspector for skills, subagents, slash commands, plugins, MCP servers, hooks, settings, memory, keybindings, and statusline. Safe edits with backups

▶️ Run Claude — spawn or resume Claude subprocesses from the browser. Pick Conversation or Headless mode, set cwd, model, permission level, and thinking effort. Same-origin guard included

💬 Run Claude · live stream — character-by-character streaming output. Tool uses, tool results, and thinking blocks are collapsible. Active runs switcher juggles multiple sessions

⚙️ Settings — model pricing editor with per-token rates, hook installation status, JSON data export, session cleanup controls, browser notification toggles, and system info panel with DB stats

🔔 Settings · Alerts — rules-based alerting engine and outbound webhooks in one place: alert rules (event pattern / inactivity / stuck agent / token threshold) with per-rule cooldown, a live fired-alert feed, and 14 first-class webhook providers plus a generic JSON endpoint with optional HMAC signing

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

# Optional: manually install hooks for container deployments
# or if auto-install on server startup fails
npm run install-hooks

# 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

PWA & Service Worker

The dashboard is a Progressive Web App with its own manifest.json and Service Worker (client/public/sw.js). The landing page and wiki are also independent PWAs with separate manifests and service workers.

All three SWs call skipWaiting() on install and delete stale caches on activate (keyed by version strings like dashboard-v1). Manifests use SVG icons (favicon.svg) with sizes="any". iOS standalone mode is enabled via apple-mobile-web-app-capable meta tags.

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" } }. The full OpenAPI 3.0 spec is served at /api/openapi.json and rendered as interactive Swagger UI at /api/docs.

📘 Swagger UI at /api/docs — auto-generated interactive playground for every REST endpoint. Try-it-out forms, request/response schema, auth headers, and curl snippets

Health

Sessions

Agents

Events, Stats, Analytics

Hooks Ingestion

Pricing

Settings

Import History

Workflows

Alerts

Webhooks

{
  "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

Import Pipeline

📥 Settings → Import History — rescan default paths, set a custom directory, or drag-and-drop .gz archives. Progress bar and result card show counts for every run

The dashboard ships with a first-class history importer that backfills sessions, agents, events, tokens, and costs from Claude Code JSONL transcripts. Live hook ingestion and manual import share the exact same parser — parseSessionFile + importSession in scripts/import-history.js — which is the architectural contract that guarantees imported token totals and cost values are identical to those captured in real time. Re-imports are idempotent: session IDs are the dedup key and compaction baseline_* columns preserve pre-compaction token totals.

Three Modes, One Pipeline

Upload Request Sequence

Idempotence & Cost Accuracy

Supported Source Layouts

Safety Model

Environment Variables

WebSocket Progress Events

Every import emits import.progress messages on /ws. Messages are throttled to at most one every ~150 ms to avoid flooding the channel on multi-thousand-session imports; the terminal complete and error frames are never throttled.

{
  "type": "import.progress",
  "timestamp": "2026-04-18T15:48:34.123Z",
  "data": {
    "importId": "upload-1729264114000",
    "phase": "parse",
    "source": "upload",
    "processed": 184,
    "total": 512,
    "current": "/tmp/ccam-import-work-xyz/project/<uuid>.jsonl",
    "counters": { "imported": 120, "backfilled": 40, "skipped": 20, "errors": 4 }
  }
}

Phases: start → scan → extract (upload only) → parse → complete, with error / extract_error replacing complete on failure.

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 terminal with colored JSON output, argument prompts, error formatting, and session-aware context for rapid testing

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 — always-visible bar showing context window usage, token counts, active model, git branch, and session ID. Configurable segments with theme support

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, per-direction token counts, session cost in USD, and git branch.

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

Installation

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

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

VS Code Extension

🔌 Sidebar — live health, analytics, and deep navigation links

The Claude Code Agent Monitor is a premium, high-fidelity extension designed to minimize context switching for AI engineers. It brings the full power of the dashboard directly into VS Code, allowing you to monitor complex subagent orchestration without ever leaving your active code file.

📖 Full developer guide: vscode-extension/README.md

Desktop App (macOS & Windows)

The dashboard ships as an optional native desktop application — a desktop/ workspace that wraps the existing server and client into a macOS .app (distributed as a .dmg) and a Windows .exe (an NSIS installer plus a no-install portable build) you install once and forget. desktop/ is a sibling workspace to client/, server/, mcp/, and vscode-extension/, built with Electron 35. It embeds the Express server in-process — it require()s server/index.js directly in the same Node runtime as the Electron main process (no child process, no IPC) — and renders the already-built React client in a BrowserWindow. Everything you see in the browser at localhost:4820 lives inside this window, with native OS lifecycle on top.

🍎🪟 The full dashboard, natively on macOS and Windows — same React client, same Express server, real BrowserWindow. Menu-bar / notification-area (tray) icon included. Shipped as a macOS DMG and a Windows EXE (macOS shown) — see DESKTOP.md.

🪟 The same dashboard as a native Windows app — real BrowserWindow with the native Windows window menu, live Activity Feed, and the Tabby companion. A notification-area (system tray) icon sits beside the clock for quick access.

In-Process Architecture

The Electron main process hosts the embedded server and manages the window, tray, and menus. The renderer is just Chromium loading http://127.0.0.1:<port> — the same origin a normal browser would use.

What It Adds

Data Persistence & CLI Reliability

Two packaging realities — a read-only application bundle / install directory and (on macOS) the minimal PATH a Finder-launched app inherits — are handled automatically so installs survive updates and the Run Claude feature works out of the box on both macOS and Windows.

Port Discovery

On launch the Electron main process picks a free port. If a healthy dashboard server already answers /api/health on port 4820 (for example, you ran npm start in a terminal), the app adopts that server instead of starting a second one — no double-binding, no SQLite contention. An adopted server is not owned by the app, so quitting leaves it running.

How to Get It

Three ways to obtain the desktop app — the latest GitHub Release (best for most users), a per-commit CI artifact (fresher than the latest release), or a local build.

Option A — download the latest GitHub Release (recommended)

Open Releases → latest and download the asset for your platform. The macOS and Windows Desktop CI jobs auto-publish a new vX.Y.Z release every time the version in package.json is bumped on master, so this link always points at the current build. Releases are public — no GitHub sign-in required.

Option B — per-commit CI artifact

Want a build straight off the tip of master, ahead of the next tagged release? Every green run of the 🍎 macOS Desktop (DMG) job on macos-latest uploads the universal DMG as the ClaudeCodeMonitor-dmg workflow artifact, and the 🪟 Windows Desktop (EXE) job on windows-latest uploads the installer + portable EXEs as the ClaudeCodeMonitor-win artifact. Open the latest passing run , scroll to its Artifacts section, and download ClaudeCodeMonitor-dmg or ClaudeCodeMonitor-win. (GitHub sign-in required; 14-day retention.)

Option C — build locally

From the project root, after git clone:

# 1. Install root + client + vscode-extension deps
npm run setup

# 2. Build the React client (the SPA the Electron window loads)
npm run build

# 3. Install Electron + electron-builder under desktop/
#    (also fetches better-sqlite3 as a prebuilt Electron binary)
#    Preflights the native better-sqlite3 build; on failure it prints
#    copy-pasteable setup help (incl. a no-toolchain alternative) and exits non-zero
npm run desktop:install

# 4a. ON macOS — build a DMG, pick ONE:
npm run desktop:dmg:arm64    # Apple Silicon only — fast (~1 min), recommended
npm run desktop:dmg:x64      # Intel only — fast
npm run desktop:dmg          # universal (x64 + arm64) — for release, SLOW

# 4b. ON Windows — build an EXE, pick ONE:
npm run desktop:win          # NSIS installer → ClaudeCodeMonitor-Setup--x64.exe
npm run desktop:win:portable # no-install portable → ClaudeCodeMonitor--x64-portable.exe

# electron-builder packages for the HOST OS — build DMGs on a Mac, EXEs on Windows.
# Each desktop:dmg* build wipes release/ first and emits a single arch-labelled
# DMG, so the volume title states the architecture (e.g. "Claude Code Monitor
# (Apple Silicon)") — no ambiguity when more than one DMG is on disk.
open desktop/release/ClaudeCodeMonitor-*-arm64.dmg   # match the arch you built

Install

macOS

# After dragging the app into /Applications:
xattr -cr "/Applications/Claude Code Monitor.app"

Alternatively, open System Settings → Privacy & Security, find the blocked app, and click Open Anyway. Code signing and Apple notarization are opt-in for the maintainer — when configured, this warning goes away for everyone.

Windows

1️⃣ NSIS installer, step 1 — Choose Installation Options: pick per-user setup and optional shortcuts.

2️⃣ NSIS installer, step 2 — Choose Install Location: defaults to %LOCALAPPDATA%\Programs\Claude Code Monitor, or point it anywhere.

3️⃣ NSIS installer, step 3 — Completing Setup: click Finish to launch the app and drop the tray icon in the notification area.

📖 User-facing guide: DESKTOP.md · architecture & contributor reference: desktop/README.md

Settings Page

⚙️ Settings — model pricing editor, hook installation toggle, JSON data export, session cleanup, browser notification preferences, and system info panel with DB stats

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

Alerts & Webhooks

🔔 Settings · Alerts — the rules-based alerting engine, a live fired-alert feed, and outbound webhook channels (14 first-class providers + a generic JSON endpoint) managed together in one place

Turns the dashboard from passive viewing into active monitoring. A rules-based alerting engine evaluates the live event stream server-side, and fired alerts fan out to outbound webhook channels. Everything lives in one place — Settings → Alerts — behind a segmented control with three tabs: Rules (what triggers an alert), Channels (where alerts are delivered), and Activity (the live fired-alert feed with acknowledge / acknowledge-all).

Provider payloads

{
  "event": "alert.triggered",
  "source": "claude-code-agent-monitor",
  "sent_at": "2026-06-13T17:00:00.000Z",
  "alert": {
    "id": 42,
    "rule_name": "Too many errors",
    "rule_type": "event_pattern",
    "session_id": "sess-1",
    "agent_id": "agent-1",
    "message": "5 matching events in 2 min (threshold 5)",
    "details": { "observed_count": 5 },
    "triggered_at": "2026-06-13T17:00:00.000Z"
  }
}

Update Notifier

⬆ Update Notifier — version comparison modal with one-click copy of the update command. No automatic self-restart; you stay in control of when upgrades happen

A detection-only subsystem that tells the user when the dashboard's git checkout is behind the canonical default branch. Branch- and fork-aware: if an upstream remote is configured (the standard convention for forks), it takes priority over origin; the chosen remote's master / main / HEAD is the comparison ref. The printed command adapts to the user's situation — git pull --ff-only only when their branch actually tracks the canonical ref, otherwise git fetch (with a fast-forward merge in the fork case). The server never pulls or restarts itself — the user runs the command in a terminal — so the mechanism cannot break dev sessions, pm2/systemd/launchd/Docker supervision, or leave orphaned processes.

API Surface

Connection Status

◈ Connection Status — sidebar-launched details modal with WebSocket endpoint, connection uptime, 60-second throughput sparkline, top event-type breakdown, and recent activity list

The Live / Disconnected pill in the sidebar footer opens a small details panel about the dashboard's WebSocket transport. It surfaces the active ws:// endpoint, how long the current socket has been up, total events received, the top event types as a horizontal bar chart, a 60-second throughput sparkline, and the most recent 8 events as an activity list. Cumulative stats (totals, type breakdown, recent list) persist across reloads via localStorage under sidebar-connection-stats; the rolling sparkline and "connected since" timer are intentionally ephemeral since they only make sense relative to "now". A Reset button clears everything on demand.

Implementation note: per-event state lives in useRef buffers on the sidebar so the WS firehose never re-renders the navigation tree — the modal does its own one-second tick to sample the refs while open. Writes are throttled (single-flight timer, 2 s window) and flushed on pagehide / visibilitychange so the latest events aren't lost to the throttle window. The modal itself is portalled to document.body so the sidebar's stacking context can't trap it.

Internationalization (i18n)

The entire UI ships in three languages — English, 简体中文, and Tiếng Việt — built on i18next + react-i18next with i18next-browser-languagedetector. Coverage is end-to-end: every page, chart tooltip, Settings flow, Workflow narrative, Config Explorer tab, Run page, and the Alerts rule-help tooltips + webhook setup guides are translated. Switch languages from the sidebar (EN / 中文 / VI) — the choice persists in localStorage.

🐾 Tabby — Reactive Cat Companion

Tabby is a cute SVG cat companion pinned to the edges of every page of the dashboard. It is always present and turns the live session stream into glanceable, ambient feedback — calm when idle, alert when something needs attention, and celebratory when a run finishes. Tabby is built entirely on the existing eventBus WebSocket stream: no new backend, no API key, and no new dependencies. The component lives in client/src/components/Tabby/ and can be toggled on or off in Settings page.

📥 Tabby Companion — a cute SVG cat in the edges of every page, reacting in real time to the live session stream with eight distinct moods and animations, auto-surfacing speech bubbles for notable events, and serving as the gateway to a status panel and Ask box

Reactive Mascot — Eight Moods

Tabby derives one of eight moods from the live session WebSocket stream, each with its own animation. The eyes track your cursor, and the active mood drives a distinct motion cue.

Auto-Surface Speech Bubbles

Notable events — session started or finished, errors, and run completed — automatically surface a speech bubble. Bubbles are throttled and coalesced so bursts of events never spam you, and they can be muted on demand. Everything reflects in real time over the existing eventBus WebSocket channel, with no polling and no extra services.

The ⌘B Panel

Click the cat — or press ⌘B / Ctrl+B — to open Tabby's panel (Esc closes it). The panel groups a live status line, quick actions, and an Ask box.

• Live status line: N live · M errored · connection state, updated from cached data.
• Quick actions: jump to Run Claude, Activity, Sessions, or errored sessions; mute bubbles; clear alerts.
• Ask box: answers simple status questions locally from cached data (“what's running”, “any errors”, “status”).

Ask → Run Claude Handoff

The Ask box answers status questions instantly and offline from cached data. For anything beyond a simple status question, Tabby hands off to the existing Run Claude page (/run?prompt=...) to spawn a real Claude Code session — so there is never a separate model call, key, or service to manage.

Accessibility & Resilience

• Fully keyboard operable: ⌘B / Ctrl+B to open, Esc to close.
• Status and bubbles announce via aria-live for screen readers.
• Respects prefers-reduced-motion to calm animations.
• Degrades gracefully to a calm, dimmed disconnected state when offline.

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