Agent Dashboard for Claude Code & Codex

Real-time monitoring platform for Claude Code & Codex agent activity 🚀

A professional dashboard to track and visualize your Claude Code and Codex agent sessions, tool usage, and subagent orchestration in real-time. Built with Node.js, Express, React, and SQLite, it integrates directly with Claude Code and Codex via their native hook systems for seamless session tracking and analytics.

[!TIP] See also: README-CN.md (中文版本), README-VN.md (Phiên bản tiếng Việt), README-KO.md (한국어 버전), and README-ES.md (versión en español) for localized documentation with region-specific tips and best practices.

[!NOTE] Need task-first help? The GitHub Wiki is the practical handbook for everyday use, team operations, troubleshooting, CLI/MCP automation, and deployment recipes. The localized static Wiki remains the English, Vietnamese, Chinese, Korean, and Spanish product and architecture tour; exact technical contracts stay in docs/.

Table of Contents

• Overview
• Internationalization (i18n)
• Features
• Quick Start
• How It Works
• Configuration
• npm Scripts
• Plugin Marketplace
• Agent Extensions
• MCP Integration
• API Reference
• Hook Events
• Browser Notifications
• Update Notifier
• Tabby — Floating Cat Companion
• Sound Cues
• Connection Status Modal
• VS Code Extension
• Desktop App (macOS & Windows)
• Data Storage
• Statusline
• Server Architecture
• Client Routing
• Hook Handler Flow
• Deployment Modes
• Project Structure
• Troubleshooting
• Contributing
• License

Overview

Track sessions, monitor agents in real-time, visualize tool usage, and observe subagent orchestration through a professional dark-themed web interface. Integrates directly with Claude Code & Codex via their native hook systems.

graph LR
    A["Claude Code<br/>Session"] -->|hooks fire on<br/>tool use / stop| B["Hook Handler<br/>(Node.js script)"]
    B -->|HTTP POST| C["Dashboard Server<br/>(Express + SQLite)"]
    C -->|WebSocket<br/>broadcast| D["Dashboard UI<br/>(React + Tailwind)"]
    style A fill:#6366f1,stroke:#818cf8,color:#fff
    style B fill:#1a1a28,stroke:#2a2a3d,color:#e4e4ed
    style C fill:#1a1a28,stroke:#2a2a3d,color:#e4e4ed
    style D fill:#10b981,stroke:#34d399,color:#fff

In addition to the real-time monitoring dashboard, it also includes a local MCP server implementation in mcp/ that exposes a catalog of tools for introspecting and managing the dashboard itself, making it easy to integrate dashboard operations directly into your Claude Code & Codex workflows. There is also an agent extension layer, which provides Claude Code & Codex plugins, skills, and subagents for dashboard interaction, analytics, and workflow intelligence.

Internationalization (i18n)

The UI ships with built-in locale switching for English (en), Chinese (zh), Vietnamese (vi), Korean (ko), and Spanish (es). A custom language dropdown prevents the selector from crowding the sidebar as more locales are added. Language resources are loaded by namespace and persisted through browser storage for stable user preference across refreshes.

flowchart LR
    A["User selects language<br/>en / zh / vi / ko / es"] --> B["i18next detector<br/>localStorage -> navigator"]
    B --> C["Resolved language<br/>fallback: en"]
    C --> D["Namespace resources<br/>common/nav/dashboard/..."]
    D --> E["React useTranslation hooks"]
    E --> F["Localized UI + accessibility labels"]

For full architecture and operational guidance, see docs/I18N.md.

User Interface

Comes with a sleek dark theme, responsive design, and intuitive navigation to explore your agent activity:

📡 Dashboard · Monitor — overview stats, active agent cards, and recent activity feed

📋 Task Progress · Overview — Dashboard agent cards and Sessions rows reuse the same compact completion donut beside status; hover or focus opens an owner-aware preview of current work and task states

🩺 Dashboard · Health — composite health score ring, storage engine donut chart, cache hit / error / success gauges, tool invocation bars, subagent effectiveness, model token distribution, and compaction stats — all auto-refreshing every 5 s

📋 Kanban Board (agents) — agents grouped by status across 4 columns: Working / Waiting / Completed / Error. The yellow Waiting column surfaces sessions blocked on user input (permission prompts, end-of-turn, or sitting at a fresh prompt) — hover a Waiting badge to see why (Needs input / Turn done / At prompt / Interrupted). Each card shows model, cost, and current tool at a glance.

🗂️ Kanban Board (sessions) — sessions grouped by status across 5 columns: Active / Waiting / Completed / Error / Abandoned, toggleable from the same page. Hover any column header for a tooltip explaining the lifecycle transition.

📂 Sessions — searchable, filterable, server-paginated table of every recorded session with cost, model, agent count, and duration; the project picker supports searchable multi-selection and sorting uses a custom menu

🤖 Session Detail · Agents — real-time overview tiles (events, tool calls, subagents, compactions, errors, duration), top-tool usage bars, subagent type breakdown, token flow, and the agent hierarchy tree

✅ Task Progress · Session Detail — the full owner-aware tracker combines a segmented completion donut, active task, completion bar, owner breakdown, and a task list paginated at 10 rows per page

💬 Session Detail · Conversation — live transcript viewer with markdown rendering, syntax-highlighted code blocks (line numbers + copy), per-tool styled tool calls, slash-command pills with their captured TUI output, and inline session-rename markers

🔬 Session Detail · Timeline — chronological event timeline with multi-dimension filters, Pre/Post grouping by `tool_use_id`, and tool-aware payload renderers

📰 Activity Feed — real-time event log with pause / resume, grouping, multi-dimension filters, and a "Session →" jump button per row

📊 Analytics — token usage by model, tool frequency, activity heatmap, and session trends with live / offline indicator; long chart legends paginate while short legends stay unchanged

🔀 Workflows — agent orchestration DAGs, tool execution Sankey diagrams, collaboration networks, bounded data-driven legends, and 11 interactive sections of workflow intelligence

🧬 Workflow Runs (Workflows page) — "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 (Session detail) — 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

🧰 Agent Config — switch between the full Claude Code explorer and a live Codex workspace for defaults, models, profiles, MCP, projects, skills, rules, hooks, plugins, and instructions. Codex previews redact secrets; its user-maintained config, hooks, rules, skills, and instructions can be edited safely with backups.

🧰 Codex Config Explorer — the Codex workspace brings together config.toml, account models, profiles, MCP servers, projects, skills, hooks, rules, plugins, and instructions. Edit supported user-managed files with timestamped backups; config.toml is edit-only.

🧩 Claude Config Explorer · Skills — the Skills tab lists every discovered skill (user, project, and plugin) with its description and source, is searchable across the whole set, and opens any skill file for a safe, timestamp-backed edit

▶️ Run Agent — choose Claude Code or Codex every time you open the launcher. Claude keeps Conversation / One-shot controls; Codex starts a native interactive app-server thread with its own approval and sandbox controls. Codex models come from the signed-in CLI catalog, while Claude lists observed models plus its supported aliases.

💬 Run Agent · live stream — Claude stream-json and Codex app-server events both render as a chat, including reasoning, command, file-change, and tool activity. Dashboard Runs lets you leave an agent working in the background and re-attach later.

⚙️ Settings — model pricing rules, hook installation status, data management, notification preferences, and system info

🔔 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 (Slack, Discord, Teams, Google Chat, Mattermost, Rocket.Chat, Telegram, PagerDuty, Opsgenie, Splunk On-Call, Zapier, Make, n8n, Pipedream) plus a generic JSON endpoint with optional HMAC signing

🛰️ Settings · Remote Data Sources — pull Claude Code and Codex activity from other machines over SSH: optionally set independent Remote Claude home and Remote Codex home paths, test each provider, sync manually or on a background poller, and switch the global data scope between local, all sources, or a specific machine, with per-session source badges

The sidebar provides quick access to the Dashboard, Kanban Board, Sessions list, Activity Feed, Analytics, Workflows, and Settings. Each page is designed to give you deep insights into your Claude Code agent activity with real-time updates and rich visualizations.

Features

The dashboard offers a comprehensive set of features to monitor and analyze your Claude Code sessions and agents:

Cursor sessions too (informational): CCAM ingests whatever agent transcripts land under ~/.claude — on this machine and on synced remotes. Cursor usage counts the same way: Cursor happens to store its agent sessions in those paths alongside Claude Code. CCAM does not distinguish which app wrote a file.

Provider scope and homes: Settings keeps the Claude Code / Codex / Both choice globally consistent, and lets you change either session-data home without restarting the dashboard.

Local safety boundaries: Run Agent accepts any existing absolute working directory and canonicalizes it before use, so home and recent-project launches remain supported. Hosted webhook providers require HTTPS; generic and n8n targets may use HTTP for local/self-hosted receivers, and delivery never follows redirects.

Quick Start

Prerequisites

• Node.js >= 22.22.0 (24 LTS recommended)
• npm >= 9.0.0

1. Install

git clone https://github.com/hoangsonww/Claude-Code-Agent-Monitor.git
cd Claude-Code-Agent-Monitor
npm run setup

2. Configure Claude Code Hooks

npm run install-hooks

The installer opens an interactive multi-select: use arrow keys, Space, and Enter to choose Claude Code, Codex (beta), or both (Claude Code is preselected). Claude Code entries live in ~/.claude/settings.json; Codex entries live in ~/.codex/hooks.json. If a selected dashboard hook set already exists, it warns before replacing only this dashboard's entries — unrelated hooks are preserved. You can make the same selection later in Settings → Hook Configuration → Install hooks.

On first dashboard entry, choose the data source and the app checks hook readiness only for that selection. Claude Code requires Claude hooks, Codex requires Codex hooks, and Both requires both hook sets. When every required hook set is already installed, the dashboard opens immediately. Otherwise the setup gate lists and installs only the missing selected providers, while preserving unrelated hooks and letting a failed status check fall back safely to manual setup.

Codex rollouts in ~/.codex/sessions are also discovered continuously. The dashboard reads their append-only JSONL incrementally, prioritizes the newest rollouts, and isolates a bad historical file for retry, so sessions, tokens, costs, conversation rows, and WebSocket updates stay current even if a hook notification is missed.

Codex rollout lifecycle records drive the same live card states as Claude Code: user_message and task_started mark the main agent Working; task_complete leaves the session active but shows Waiting; and turn_aborted shows Waiting with an interrupted reason. A new rollout record self-heals an erroneously completed session. On supported local hosts, liveness is matched to the exact rollout-*.jsonl held open by each Codex process, so old rollouts that share a project directory are imported as completed instead of appearing as phantom active agents. The Node launcher and its native Codex child are collapsed into one logical process, so one TUI produces one card.

Codex /rename titles are read from its native session index and update session and agent cards in real time. Its conversation replay includes human turns plus exec custom-tool calls and outputs, with cursor pagination that loads older messages at the top of the transcript.

Claude Code and Codex cards show a compact, two-row history of their latest distinct human prompts beneath the provider-native title, so a short friendly name or terse follow-up never hides the active task. Claude refreshes this context from its local transcript cache during live hooks, imports, and watchdog sweeps; Codex refreshes it from rollout records and falls back to persisted user_message events for older imports. The transcript renders persisted PNG/JPEG/GIF/WebP attachments for Claude Code and Codex when available, while duplicate Codex response/event copies collapse into one human turn.

Codex response_item tool invocations are indexed once through a dedicated rollout cursor, so its Workflows tool flow, session drill-in, model/token totals, and context_compacted counts reflect the recorded Codex data without replaying lifecycle or token counters. In a Codex-only dashboard scope, the Claude Code-only Dynamic Workflows journal panel is hidden rather than presented as empty Codex data.

3. Start

# Development (hot reload on both server and client)
npm run dev

# Production (single process, built client)
npm run build && npm start

[!TIP] Makefile alternative — all commands are also available via make if you have it installed on your system. Run make help to see every target, or use shortcuts like make dev, make build, make test, etc.

4. Open

5. Optional: Run the local MCP server

npm run mcp:start              # stdio (default — 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
ccam mcp stdio                 # stable launcher used by bundled plugins

npm run setup installs and builds the MCP package before linking ccam. For stdio mode, configure your host with command ccam and args ["mcp", "stdio"].

For HTTP mode, point remote MCP clients at http://127.0.0.1:8819/mcp (Streamable HTTP) or http://127.0.0.1:8819/sse (legacy SSE).

See mcp/README.md for full host configuration, transport details, safety flags, and tool catalog.

Optional: Seed Demo Data

npm run seed

Creates 8 sample sessions, 23 agents, and 106 events so you can explore the UI immediately.

Alternative: Desktop App (macOS & Windows)

If you'd rather not keep a terminal open, install the optional native desktop app. It embeds the server in-process, adds a menu-bar / notification-area (tray) icon, and supports auto-start at login (macOS Login Items / Windows startup).

The fastest path is to download a pre-built installer from the latest GitHub Release (CI auto-publishes a vX.Y.Z whenever package.json is bumped on master):

• macOS — grab ClaudeCodeMonitor-<version>-arm64.dmg (Apple Silicon) or -x64.dmg (Intel) and drag Claude Code Monitor.app into /Applications.
• Windows — grab ClaudeCodeMonitor-Setup-<version>-x64.exe (installer) or ClaudeCodeMonitor-<version>-x64-portable.exe (no-install) and run it.

To build it yourself instead:

npm run desktop:install        # install Electron + electron-builder into desktop/ (preflights native deps; prints setup help on failure)
npm run desktop:dmg:arm64      # macOS: fast single-arch DMG (Apple Silicon)
npm run desktop:win            # Windows: NSIS installer .exe (run on Windows)

Full coverage of the desktop app — download, install, tray/menu features, build commands, and signing — is in the Desktop App (macOS & Windows) section below. See also DESKTOP.md (user guide) and desktop/README.md (architecture).

Alternative: Docker / Podman

The OCI image and Compose files support Docker and Podman. The runtime is non-root, drops all capabilities, uses Tini as PID 1, includes Git/OpenSSH/SQLite, and becomes read-only except for /app/data, /app/config, and /tmp.

# Dashboard only
docker compose up -d --build
# or
podman compose up -d --build

# Complete stack: dashboard + authenticated MCP + Nginx + Prometheus + Grafana
umask 077
openssl rand -hex 32 > deployments/secrets/dashboard-token
openssl rand -hex 32 > deployments/secrets/hook-token
openssl rand -hex 32 > deployments/secrets/mcp-token
openssl rand -base64 32 > deployments/secrets/grafana-admin-password
npm run docker:full:up

All host ports bind to loopback by default: dashboard 4820, MCP 8819, Nginx 8080, Prometheus 9090, and Grafana 3000. Claude and Codex homes are mounted read-only; named volumes persist SQLite and dashboard-owned configuration. Nginx proxies the UI, authenticated REST API, and WebSocket, while hooks, metrics, and MCP stay blocked at the edge unless explicitly enabled. The optional agent-runtime Docker target adds pinned Claude Code and Codex CLIs for container-native Run Agent workflows.

[!IMPORTANT] Install Claude Code/Codex hooks on the host after the container starts. For remote cloud hooks, set CCAM_DASHBOARD_URL=https://... and a separate CCAM_HOOK_TOKEN; non-loopback hook URLs require HTTPS. See DEPLOYMENT.md.

How It Works

The dashboard integrates with Claude Code via its native hook system to provide real-time monitoring of agent activity. Here's an overview of the architecture and data flow:

sequenceDiagram
    participant CC as Claude Code
    participant HH as Hook Handler
    participant API as Express Server
    participant DB as SQLite
    participant WS as WebSocket
    participant UI as React Client

    CC->>HH: stdin (JSON event)
    HH->>API: POST /api/hooks/event
    API->>DB: Insert/update records
    API->>WS: Broadcast update
    WS->>UI: Push message
    UI->>UI: Re-render component

    Note over CC,HH: Hooks fire on SessionStart,<br/>PreToolUse, PostToolUse,<br/>Stop, SubagentStop,<br/>SessionEnd, Notification.<br/>Compaction detected from JSONL
    Note over API,DB: Transactional writes<br/>with auto session/agent creation
    Note over WS,UI: ~0ms latency,<br/>no polling

[!IMPORTANT] See ARCHITECTURE.md for a deep dive into the server architecture, database schema, API routes, WebSocket design, client routing, hook handler flow, deployment modes, and detailed lifecycle diagrams for sessions and agents.

Hook Lifecycle

1. Claude Code fires a hook on session start, tool use, turn end, subagent completion, and session exit
2. Hook Handler (scripts/hook-handler.js) reads the JSON event from stdin, resolves live dashboards via ~/.claude/.agent-dashboard.json (or CLAUDE_DASHBOARD_PORT if set), and POSTs the same payload to one ingest target per unique SQLite data directory (lowest port wins when Docker and npm run dev share ~/.claude/agent-dashboard, so events are never double-ingested). Servers with different databases (e.g. the desktop app using its own Application Support dir alongside npm run dev) still each receive hooks. Fails silently with a 5 s safety-net timeout so it never blocks Claude Code, and per-target promises never reject so a single dead listener can't starve the others.
3. Server processes the event inside a SQLite transaction:
   • Auto-creates sessions and main agents on first contact
   • Detects Agent tool calls to track subagent creation
   • On SessionStart, stamps the session and main agent's awaiting_input_since so a fresh CLI sitting at the prompt lands in Waiting immediately
   • On UserPromptSubmit (user hits enter), clears the waiting flag and promotes the main agent to working — the only reliable signal that text-only assistant turns have started, since they emit no PreToolUse
   • Sets agent to "working" on PreToolUse (also clears the waiting flag), keeps it working through PostToolUse
   • On Stop (Claude finishes responding), main agent goes to "waiting" — Claude finished its turn, ball is in the user's court. Background subagents continue running. Session stays active. Stop with stop_reason=error marks the agent error and the session error
   • On a permission Notification (matched by message pattern: permission, waiting for input, needs your approval, …), sets the agent to waiting and stamps awaiting_input_since
   • SubagentStop deliberately does NOT clear the waiting flag (a backgrounded subagent finishing tells us nothing about the human)
   • Marks subagents completed individually via SubagentStop. After res.json() returns, fires a fire-and-forget scanAndImportSubagents pass that walks the session's subagents/agent-*.jsonl files, pairs tool_use ↔ tool_result blocks by tool_use_id, and emits PreToolUse + PostToolUse events under each subagent's own agent_id — closing the gap where subagent-internal tool calls would otherwise be invisible to the dashboard
   • On SessionEnd (CLI process exits), drops the waiting flag. If the session is in error, the error state is preserved; otherwise marks all agents + the session as completed
   • On SessionStart, any other active session with no activity for DASHBOARD_STALE_MINUTES (default 180 = 3 h, env-overridable) is automatically marked "abandoned" with its agents completed. This handles /resume inside a session, Ctrl+C, and other scenarios where a session is orphaned without a clean SessionEnd
   • Reactivates completed/error/abandoned sessions when new work events arrive (session resumed). Stop and SubagentStop events also reactivate completed/abandoned sessions — this handles pre-existing sessions imported before the server started, where the first hook event may be a Stop
   • Error recovery: only UserPromptSubmit and PreToolUse can recover a session from error back to active — indicating the user actively retried
   • Detects conversation compaction (isCompactSummary entries in the JSONL transcript) and creates Compaction agents + events. Token baselines are preserved across compactions so no usage is lost. Transcript reads use a shared stat-based cache with incremental byte-offset reads — only new bytes appended since the last read are parsed, giving ~50x speedup for long sessions
   • Extracts API errors (isApiErrorMessage entries: quota limits, rate limits, invalid_request) and raw type: "error" responses from JSONL transcripts, stored as APIError events. Turn durations (system subtype turn_duration) are stored as TurnDuration events. Tool result errors (toolUseResult.is_error) are tracked as ToolError events
   • Error detection watchdog — a background timer runs every 15 seconds, scanning active sessions with no recent hook events (>10 s stale). It re-reads their transcript files looking for API errors (auth failures, rate limits, quota exhaustion), derives transcript paths from session cwd for imported sessions without transcript_path in event data, and marks sessions/agents as error when API errors are found. This catches cases where the Claude CLI does not fire a hook after an API error (e.g., 401 auth failures where the CLI shows the error and waits)
   • User-interrupt (Esc) recovery — cancelling a turn with Esc fires no hook (a documented Claude Code limitation), so without intervention the main agent would stay stuck in working forever. The same 15 s watchdog recovers these two ways: (1) when the cancel leaves a [Request interrupted by user] marker in the transcript (Esc after some output), the transcript cache flags it via pendingInterrupt — derived purely from transcript ordering (latest interrupt vs latest real turn activity, same clock, so it works even for a sub-second cancel) — and the session moves to Waiting within ~15 s; (2) when Esc is pressed before any output, Claude Code writes no marker at all, so an idle-timeout fallback applies — if the main agent has been working with no tool in flight and neither a hook event nor the transcript has advanced for DASHBOARD_WORKING_IDLE_SECONDS (default 120), the turn is treated as dead and the session moves to Waiting. Both paths log an Interrupted event and land the session in the same Waiting state a normal Stop produces. Streaming output (transcript still growing) and in-flight tool calls (current_tool set) are exempt; a rare false flip self-heals on the next real hook
   • Dead-session liveness reap — quitting Claude Code (Ctrl+C, closing the terminal) fires a SessionEnd hook, but if the dashboard isn't running at that moment the event is lost forever and the session would sit in Waiting until the stale sweep (3 h by default). The same 15 s watchdog closes the gap with a process-liveness probe: it lists running claude CLI processes (ps + lsof on macOS, /proc on Linux) and completes any active session whose cwd has no live claude process — landing it in the same completed state a real SessionEnd produces, with a synthetic SessionEnd event on the timeline. Guards: on watchdog ticks the session's transcript must not have been written for at least DASHBOARD_LIVENESS_IDLE_SECONDS (default 60; the last hook write is the fallback clock when no transcript exists on disk) — the boot passes skip this gate entirely, so a session quit even one second before launch clears immediately — and the probe reports "no answer" (changing nothing) on Windows, inside containers (host processes are invisible there), when ps/lsof fail, or when explicitly disabled via DASHBOARD_LIVENESS_PROBE=0. In a mixed deployment the reap also auto-skips any session whose cwd is not POSIX-absolute — a session forwarded from another machine via household hooks reports the origin's own path (e.g. a Windows D:\Git\ai-deck) that a local ps/lsof//proc scan can never match, so remote sessions are protected without disabling the probe for genuinely-local ones. Remote Data Source sessions (sessions.source ≠ local) are always skipped too — their cwd is legitimately POSIX-absolute on another machine, so the local process probe says nothing about them; their lifecycle is owned entirely by the remote-sync reconciliation described above. A false completion self-heals: the next hook event reactivates the session. Besides the 15 s watchdog cadence, the reap runs immediately at startup (clearing dead sessions already in the DB from a previous run before they ever render) and again ~5 s later (covering sessions the startup sync just imported), so a session that died while the dashboard was down never shows as Waiting
   • A periodic server sweep catches abandoned sessions and new compactions that slipped past event-based detection (e.g., /compact fires no hook, /resume within seconds of session creation). Cadence is derived from DASHBOARD_STALE_MINUTES (¼ of the threshold, clamped to 60 s – 5 min). The sweep reads transcript_path directly off each active session row (a small index lookup) instead of scanning the events table for it; the column is populated by the hook handler the first time it sees a transcript path and is one-time-backfilled from existing events by the db.js migration, with a partial index idx_sessions_active_tp covering exactly the rows the sweep reads. The sweep shares the transcript cache with the hook handler, avoiding duplicate I/O. Abandoned session cleanup also evicts the transcript cache entry to bound memory. Remote Data Source sessions (source ≠ local) remain mirror-owned only while their matching Claude Code or Codex provider is healthy; if that provider is unavailable, errors, or is stranded in syncing, the periodic and startup cleanup use the normal stale rule so an old Waiting card cannot persist forever
   • Continuous project sync (startSessionSync) keeps ~/.claude/projects discoverable beyond the one-time, marker-gated startup backfill: a project added later whose sessions never flow through hooks would otherwise stay invisible until a manual rescan. An immediate startup sweep, a debounced fs.watch (recursive on macOS/Windows; root + immediate children on Linux), and a DASHBOARD_SESSION_SYNC_MS poll (default 30 s; 0 disables the poll, watcher stays) share one mtime cache and a coalesced sweep that re-parses only files whose mtime advanced — and skips an already-imported, unchanged session without re-parsing, so restart cost stays O(new/changed files). Each newly discovered/grown session broadcasts session_created/session_updated plus its main agent, the same frames hooks emit
4. WebSocket broadcasts the change to all connected clients
5. UI receives the update and re-renders the affected components in real-time with no polling.

Agent State Machine

Persisted statuses: working | waiting | completed | error. The awaiting_input_since column is supplementary — it tracks when the agent started waiting and is used for duration display, but waiting is now a real persisted status.

stateDiagram-v2
    [*] --> waiting: ensureSession (first hook)
    waiting --> working: PreToolUse / UserPromptSubmit / Codex task_started / user_message
    working --> working: PostToolUse (tool completed)
    working --> waiting: Stop, non-error / Codex task_complete
    working --> waiting: Codex turn_aborted (interrupted)
    working --> waiting: Notification (input prompt)
    working --> waiting: Esc cancel (watchdog marker or idle timeout)
    waiting --> error: Stop with error
    working --> error: Stop with error
    waiting --> error: API error detected (watchdog)
    working --> error: API error detected (watchdog)
    error --> working: UserPromptSubmit / PreToolUse (recovery)
    working --> completed: SessionEnd
    waiting --> completed: SessionEnd

    note right of waiting
        Agent is between turns or
        awaiting user input
    end note

Session State Machine

Persisted statuses: active | completed | error | abandoned. The Waiting session state is a UI overlay (status=active with awaiting_input_since set).

stateDiagram-v2
    [*] --> waiting: SessionStart startup/resume/clear (status=active + flag)
    active --> active: SessionStart compact (mid-turn — state preserved, no flag)
    waiting --> active: UserPromptSubmit / PreToolUse / PostToolUse / Codex task_started / user_message
    active --> waiting: Stop, non-error / Codex task_complete (flag re-stamped)
    active --> waiting: Codex turn_aborted (interrupted)
    active --> waiting: Permission Notification (agent → waiting)
    active --> waiting: Esc cancel (watchdog marker or idle timeout)
    active --> error: Stop, stop_reason=error
    active --> error: API error detected (watchdog)
    waiting --> error: API error detected (watchdog)
    error --> active: UserPromptSubmit / PreToolUse (recovery)
    waiting --> completed: SessionEnd (CLI exited)
    active --> completed: SessionEnd (CLI exited)
    error --> error: SessionEnd (preserves error)
    waiting --> abandoned: Stale > DASHBOARD_STALE_MINUTES (default 180)
    active --> abandoned: Stale > DASHBOARD_STALE_MINUTES
    completed --> active: Session resumed (new work event)
    error --> active: Session resumed (new work event)
    abandoned --> active: Session resumed (new work event)
    completed --> [*]
    error --> [*]
    abandoned --> [*]

Cost Calculation Flow

flowchart LR
    TU["token_usage rows<br/>(per session × model)"] --> GROUP["Group by model"]
    PR["model_pricing rules<br/>(pattern-based)"] --> SORT["Sort by specificity<br/>(longest pattern first)"]
    GROUP --> MATCH{"Match model<br/>to pricing rule"}
    SORT --> MATCH
    MATCH --> CALC["cost = Σ (tokens / 1M) × rate<br/>for input, output, cache_read, cache_write"]
    CALC --> RESULT["{ total_cost, breakdown[] }"]
    style TU fill:#003B57,stroke:#005f8a,color:#fff
    style PR fill:#6366f1,stroke:#818cf8,color:#fff
    style RESULT fill:#10b981,stroke:#34d399,color:#fff

[!IMPORTANT] The cost calculation flow is based on token usage and model pricing rules. Ensure your pricing rules are up-to-date to reflect accurate costs. Update the model pricing table via the Settings page to maintain accurate cost tracking - the dashboard does not automatically fetch pricing updates from external sources. Once you set the pricing rules, the dashboard applies them retroactively to all sessions for consistent cost reporting.

Configuration

[!IMPORTANT] Secure by default. The server binds 127.0.0.1 and is not reachable from the network out of the box (GHSA-gr74-4xfh-6jw9). To expose it on a LAN, set both DASHBOARD_HOST (e.g. 0.0.0.0) and DASHBOARD_TOKEN (which then gates /api/* and the WebSocket), and list your LAN hostnames in DASHBOARD_ALLOWED_HOSTS. See .env.example and .github/SECURITY.md for details.

For git clones, the server periodically git fetches origin and compares your checkout to origin/master, origin/main, or origin/HEAD. When you are behind, a message appears in the server terminal and a modal appears in the UI with the exact command to run. The dashboard never pulls or restarts itself — you copy the command, run it in a terminal, then restart the server the same way you started it.

ccam CLI

The dashboard's full feature surface is also available from any terminal via the dependency-free ccam CLI (bin/ccam.js). It is linked automatically by npm run setup (via npm link), after which ccam <command> works from any directory. It discovers the running dashboard through ~/.claude/.agent-dashboard.json (the same live-server registry the hook handler uses), with CLAUDE_DASHBOARD_PORT / DASHBOARD_PORT env overrides, falling back to http://127.0.0.1:4820.

# Server
ccam status                       # ● running / ○ not running indicator
ccam start [--port N]             # start the server in the background (detached)
ccam stop                         # stop the background server gracefully
ccam repl                         # interactive shell (also: shell, i)

# Monitoring
ccam health                       # is the dashboard up?
ccam stats                        # totals, today's events, status distributions
ccam kanban                       # sessions + agents grouped by status columns
ccam tail [--session <id>]        # live event feed in the terminal (Ctrl+C stops)

# Data
ccam sessions [--status s] [--q text] [--limit n]
ccam session <id>                 # detail: agent tree, cost, recent events
ccam agents   [--status s] [--session id]
ccam events   [--session id] [--limit n]

# Insights
ccam analytics                    # token totals, top tools, agent types
ccam workflows [--session id]     # workflow intelligence stats and patterns
ccam runs [--session id]          # dynamic Workflow-tool runs
ccam cost [--session <id>]        # total estimated cost with per-model breakdown
                                  # (--session scopes to one; shows tool surch