Claude-Code-Monitor/ARCHITECTURE.md

Agent Dashboard - System Design and Technical Reference

Architectural overview and technical reference for the Agent Dashboard system, covering design goals, high-level architecture, data flow, server and client components, database design, WebSocket protocol, hook integration, MCP extension layer, Claude Code plugins & skills, state management, security considerations, performance characteristics, deployment modes, and technology choices.

---

Table of Contents

• System Overview
• High-Level Architecture
• Data Flow
• Server Architecture
• Client Architecture
• Internationalization Architecture
• Database Design
• WebSocket Protocol
• Hook Integration
• Import Pipeline
• Agent Extension Layer
• Plugin Marketplace
• MCP Integration
• State Management
• Browser Notification System
• Update Notifier Subsystem
• Tabby Companion Subsystem
• VS Code Extension Architecture
• Desktop App Architecture (macOS & Windows / Electron)
• Security Considerations
• Performance Characteristics
• Deployment Modes
• Statusline Utility
• Technology Choices
• Build & Run Targets

---

System Overview

Agent Dashboard is a local-first monitoring platform for Claude Code sessions. It captures agent lifecycle events via Claude Code's native hook system, persists them in SQLite, and presents them through a React dashboard with real-time WebSocket updates.

Cursor sessions (informational): The same ~/.claude transcript paths also pick up Cursor agent sessions — Cursor happens to use that layout locally alongside Claude Code. CCAM does not distinguish which editor created a session.

C4Context
    title System Context Diagram

    Person(user, "Developer", "Uses Claude Code CLI")
    System(claude, "Claude Code", "AI coding assistant with hook system")
    System(dashboard, "Agent Dashboard", "Monitoring platform")
    SystemDb(sqlite, "SQLite", "Persistent storage")

    Rel(user, claude, "Interacts with")
    Rel(claude, dashboard, "Sends hook events via stdin + HTTP")
    Rel(user, dashboard, "Views in browser")
    Rel(dashboard, sqlite, "Reads/writes")

Design goals:

• Zero-config operation -- auto-discovers sessions from hook events
• Never block Claude Code -- hooks fail silently with timeouts
• Instant feedback -- WebSocket push, no polling
• Portable -- SQLite, no external services, runs on any OS with Node.js 20+
• Extensible -- plugin marketplace with 10 plugins (53 skills, 14 agents, 30 slash commands, 3 CLI tools)

---

High-Level Architecture

graph TB
    subgraph "Claude Code Process"
        CC[Claude Code CLI]
        H0[SessionStart Hook]
        H1[PreToolUse Hook]
        H2[PostToolUse Hook]
        H3[Stop Hook]
        H4[SubagentStop Hook]
        H5[Notification Hook]
        H6[SessionEnd Hook]
        CC --> H0 & H1 & H2 & H3 & H4 & H5 & H6
    end

    subgraph "Plugin Layer"
        direction TB
        PM["Plugin Marketplace<br/>(10 plugins, 53 skills)"]
        PA["ccam-analytics"]
        PP["ccam-productivity"]
        PD["ccam-devtools"]
        PI["ccam-insights"]
        PC["ccam-dashboard"]
        PG["ccam-cost-guard"]
        PS["ccam-sessions"]
        PW["ccam-workflows"]
        PQ["ccam-quality"]
        PF["ccam-config"]
        PM --> PA & PP & PD & PI & PC & PG & PS & PW & PQ & PF
    end

    subgraph "Hook Layer"
        HH["hook-handler.js<br/>(stdin → HTTP)"]
        H0 & H1 & H2 & H3 & H4 & H5 & H6 -->|stdin JSON| HH
    end

    subgraph "Server Process (port 4820)"
        direction TB
        EX[Express Server]
        HR[Hook Router]
        SR[Session Router]
        AR[Agent Router]
        ER[Event Router]
        STR[Stats Router]
        ANR[Analytics Router]
        WFR[Workflows Router]
        PR[Pricing Router]
        DB[(SQLite<br/>WAL mode)]
        WSS[WebSocket Server]

        EX --> HR & SR & AR & ER & STR & ANR & WFR & PR
        HR -->|transaction| DB
        SR & AR & ER & STR & ANR & WFR & PR --> DB
        HR -->|broadcast| WSS
        SR & AR -->|broadcast| WSS
    end

    subgraph "Client (Browser)"
        direction TB
        VITE[Vite Dev Server<br/>or Static Files]
        APP[React App]
        WS_CLIENT[WebSocket Client]
        EB[Event Bus]
        PAGES[Pages:<br/>Dashboard / Kanban /<br/>Sessions / Activity /<br/>Analytics / Workflows]

        VITE --> APP
        APP --> WS_CLIENT
        WS_CLIENT --> EB
        EB --> PAGES
        PAGES -->|fetch| EX
    end

    HH -->|"POST /api/hooks/event"| HR
    WSS -->|push messages| WS_CLIENT
    PA & PP & PD & PI & PC -->|"curl API"| EX

    style CC fill:#6366f1,stroke:#818cf8,color:#fff
    style DB fill:#003B57,stroke:#005f8a,color:#fff
    style WSS fill:#10b981,stroke:#34d399,color:#fff
    style EB fill:#f59e0b,stroke:#fbbf24,color:#000
    style PM fill:#8b5cf6,stroke:#a78bfa,color:#fff

---

Data Flow

Event Ingestion Pipeline

sequenceDiagram
    participant CC as Claude Code
    participant HH as hook-handler.js
    participant API as POST /api/hooks/event
    participant TX as SQLite Transaction
    participant WS as WebSocket.broadcast()
    participant UI as React Client

    CC->>HH: stdin: {"session_id":"abc","tool_name":"Bash",...}
    Note over HH: Reads stdin, parses JSON,<br/>wraps with hook_type

    HH->>API: POST {"hook_type":"PreToolUse","data":{...}}
    Note over API: Validates hook_type + data

    API->>TX: BEGIN TRANSACTION
    TX->>TX: ensureSession(session_id)
    Note over TX: Creates session + main agent<br/>if first contact. Also persists<br/>data.transcript_path onto the session row<br/>(SQL-guarded, so subsequent events no-op).<br/>Syncs sessions.name from the transcript title<br/>(custom-title &gt; ai-title &gt; first user prompt).

    TX->>TX: Process by hook_type
    Note over TX: Dispatches by hook_type. Maintains the agent and<br/>session state machines plus the awaiting_input_since flag.<br/>SubagentStop also triggers a JSONL scan that emits per_tool<br/>events under each subagent. See the hook table below for<br/>the full per_event behaviour.

    TX->>TX: insertEvent(...)
    TX->>TX: COMMIT

    API->>WS: broadcast("agent_updated", agent)
    API->>WS: broadcast("new_event", event)

    WS->>UI: {"type":"agent_updated","data":{...}}
    UI->>UI: eventBus.publish(msg)
    UI->>UI: Page re-renders with new data

Client Data Loading Pattern

sequenceDiagram
    participant Page as React Page
    participant API as api.ts
    participant Server as Express
    participant EB as eventBus
    participant WS as WebSocket

    Note over Page: Component mounts
    Page->>API: load() via useEffect
    API->>Server: GET /api/sessions (or agents, events, stats)
    Server-->>API: JSON response
    API-->>Page: setState(data)

    Note over Page: Subscribes to live updates
    Page->>EB: eventBus.subscribe(handler)

    loop Real-time updates
        WS->>EB: eventBus.publish(msg)
        EB->>Page: handler(msg)
        Page->>Page: Reload or optimistic update
    end

    Note over Page: Component unmounts
    Page->>EB: unsubscribe()

---

Server Architecture

Module Dependency Graph

graph TD
    INDEX[server/index.js<br/>Express app + HTTP server]
    DB[server/db.js<br/>SQLite + prepared statements<br/>better-sqlite3 → node:sqlite fallback]
    WS[server/websocket.js<br/>WS server + broadcast]
    HOOKS[routes/hooks.js<br/>Hook event processing]
    TC[lib/transcript-cache.js<br/>JSONL cache + incremental reads]
    SESSIONS[routes/sessions.js<br/>Session CRUD]
    AGENTS[routes/agents.js<br/>Agent CRUD]
    EVENTS[routes/events.js<br/>Event listing]
    STATS[routes/stats.js<br/>Aggregate queries]
    PRICING[routes/pricing.js<br/>Cost calculation + pricing CRUD]
    SETTINGS[routes/settings.js<br/>System info + data management]
    WORKFLOWS[routes/workflows.js<br/>Workflow visualizations]
    ALERTSR[routes/alerts.js<br/>Alert rules CRUD + feed]
    ALERTS[lib/alerts.js<br/>Rule evaluation engine]
    WEBHOOKSR[routes/webhooks.js<br/>Webhook target CRUD + test]
    WEBHOOKS[lib/webhooks.js<br/>Webhook delivery engine]
    WEBHOOKPROV[lib/webhook-providers.js<br/>14-provider registry + formatters]

    INDEX --> DB
    INDEX --> WS
    INDEX --> HOOKS & SESSIONS & AGENTS & EVENTS & STATS & PRICING & SETTINGS & WORKFLOWS & ALERTSR & WEBHOOKSR

    HOOKS --> DB & WS & TC
    HOOKS --> ALERTS
    ALERTSR --> DB & WS & ALERTS
    ALERTS --> DB & WS
    ALERTS --> WEBHOOKS
    WEBHOOKSR --> DB & WEBHOOKS & WEBHOOKPROV
    WEBHOOKS --> DB & WEBHOOKPROV
    SETTINGS --> DB & TC
    INDEX --> TC
    SESSIONS --> DB & WS
    AGENTS --> DB & WS
    EVENTS --> DB
    STATS --> DB & WS
    PRICING --> DB
    WORKFLOWS --> DB

    style INDEX fill:#6366f1,stroke:#818cf8,color:#fff
    style DB fill:#003B57,stroke:#005f8a,color:#fff
    style WS fill:#10b981,stroke:#34d399,color:#fff

Server Components

Module	Responsibility
server/index.js	Express app setup, middleware, route mounting, static file serving in production, HTTP server creation. Static middleware sets explicit Cache-Control headers — immutable for /assets/*, no-cache, must-revalidate for index.html / sw.js / manifest.json, a short revalidation window otherwise — so a rebuild always replaces the in-browser bundle without a hard refresh. Runs a periodic maintenance sweep — cadence derived from DASHBOARD_STALE_MINUTES (¼ of the threshold, clamped to 60 s – 5 min, default ~45 min) — that abandons stale sessions with transcript cache eviction and scans active sessions for new compaction entries by reading sessions.transcript_path directly (an O(active sessions) lookup; the previous SELECT DISTINCT json_extract(events.data,'$.transcript_path') scan grew with the events table and is gone). Error detection watchdog runs every 15 seconds: finds active sessions with no recent hook events (>10 s stale), re-reads their transcript files looking for API errors (401 auth, rate limits, quota exhaustion), derives transcript paths from session cwd for imported sessions, and marks sessions/agents as error when API errors are found — catches cases where the CLI doesn't fire a hook after API errors. The same watchdog also performs user-interrupt (Esc) recovery: Esc fires no hook, so a cancelled turn would otherwise leave the main agent stuck working. It detects this two ways — (a) the transcript's [Request interrupted by user] marker, surfaced as result.pendingInterrupt from TranscriptCache (computed from transcript ordering alone, immune to server/transcript clock skew), and (b) an idle-working fallback for an Esc pressed before any output (which writes no marker): when the main agent has been working with current_tool null and neither a hook event nor the transcript mtime has advanced for DASHBOARD_WORKING_IDLE_SECONDS (default 120) — and moves the session to Waiting (agent → waiting, awaiting_input_since stamped) with an Interrupted event. Triggers legacy session import (with active-session detection for recently-modified JSONL files) and compaction backfill on startup, plus a boot liveness reap — immediately for rows from a previous run and again ~5 s later for rows the startup sync just imported (see the routes/hooks.js row) — so sessions that died while the dashboard was down never render as Waiting. Also starts the Remote Data Sources sync poller (startRemoteSourceSync) that pulls each enabled remote source on an interval — DASHBOARD_REMOTE_SYNC_MS (default 60000; 0 disables) — reusing server/lib/remote-sync.js. Graceful shutdown (SIGTERM/SIGINT) tears down in order: drop realtime clients first (closeWebSocket terminates WS clients so their sockets release), then httpServer.close() to stop new connections, then httpServer.closeAllConnections() to drop lingering keep-alive sockets so close() fires promptly, and only then close SQLite — inside the close() callback, after the HTTP server has drained. Closing the DB before drain made in-flight requests throw The database connection is not open; leaving WS/keep-alive sockets open stalled the shutdown until the 5 s force-exit backstop (the "waiting for graceful termination" hang under node --watch). A second signal forces an immediate exit
server/openapi.js	OpenAPI 3.0.3 document generator for the backend API (metadata, schemas, endpoint paths), merging supplementary fragments from server/openapi-extra/ in createOpenApiSpec(). Feeds the raw spec endpoint (/api/openapi.json), Swagger UI (/api/docs), ReDoc (/api/redoc, served via server/lib/redoc.js with a self-hosted bundle — never a CDN), and the committed openapi.yaml regenerated by npm run openapi:yaml
server/lib/redoc.js	Serves the ReDoc API reference (/api/redoc) as a self-hosted three-panel rendering of the OpenAPI spec, with the ReDoc bundle served locally from /api/redoc/redoc.standalone.js (bundled via the redoc dependency, never a CDN) so the reference works fully offline / air-gapped
server/openapi-extra/	Supplementary OpenAPI path/schema fragments merged into the spec by createOpenApiSpec() — covers cc-config.js, push.js, run.js, and misc.js route groups
server/db.js	SQLite connection with WAL mode, schema migration (CREATE TABLE IF NOT EXISTS + ALTER TABLE for column additions), all prepared statements as a reusable stmts object. Tries better-sqlite3 first, falls back to node:sqlite via compat-sqlite.js. Migrations use literal defaults for ALTER TABLE since SQLite does not support expressions like strftime() in column defaults added via ALTER TABLE
server/compat-sqlite.js	Compatibility wrapper that gives Node.js built-in node:sqlite (DatabaseSync) the same API as better-sqlite3 — pragma, transaction, prepare. Used as automatic fallback when the native module is unavailable (Node 22+)
server/websocket.js	WebSocket server on /ws path, 30s heartbeat with ping/pong dead connection detection, typed broadcast function. Upgrades run through the same Host-header allowlist and optional DASHBOARD_TOKEN check as the HTTP surface (isWebSocketAuthorized)
server/lib/security.js	Network-hardening module (fix for GHSA-gr74-4xfh-6jw9). resolveHost() picks the bind address — 127.0.0.1 by default, widened only by DASHBOARD_HOST (logs a warning for non-loopback binds). hostGuard rejects requests whose Host header isn't in the loopback set or DASHBOARD_ALLOWED_HOSTS (DNS-rebinding defense). corsOptions() allows only loopback origins while letting No-Origin (curl/CLI) requests through. tokenGuard + isWebSocketAuthorized enforce the optional DASHBOARD_TOKEN on /api/* and WebSocket upgrades (accepted as Authorization: Bearer, x-dashboard-token, or ?token=; off by default). Exempt paths and token-matching helpers (tokensMatch, extractToken) live here too
routes/hooks.js	Core event processing inside a SQLite transaction. Auto-creates sessions/agents. Handles 8 hook types: SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SubagentStop, Notification, SessionEnd, plus synthetic Compaction events. Manages the agent state machine plus the awaiting_input_since overlay (stamped on SessionStart for fresh CLIs — startup/resume/clear only, since a compact-source SessionStart fires mid-turn while Claude is working and is deliberately skipped so a working session stays Active — on non-error Stop, and on permission Notifications (which now also set agent status to waiting); cleared on UserPromptSubmit / PreToolUse / PostToolUse / SessionStart-resume / SessionEnd; SubagentStop intentionally does NOT clear it; and stamped by the 15 s watchdog on user-interrupt (Esc) recovery — see the index.js row — since Esc fires no hook). After res.json() returns on SubagentStop, fires a fire-and-forget scanAndImportSubagents (from scripts/import-history.js) that parses every subagents/agent-*.jsonl, pairs tool_use ↔ tool_result blocks by tool_use_id, and emits per-tool PreToolUse + PostToolUse events under each subagent's own agent_id — closes the gap where subagent-internal tool calls would otherwise never reach the events table. The same scan also reparents nested subagents under their true spawner (see the import-history.js row); it returns { created, reparented }, and the follow-up new_event refetch nudge fires when either is non-zero so a pure re-parent (tree shape changed, no new rows) still refreshes the UI. The same scan attributes each subagent's tokens to its own model (resolved from the subagent transcript) and stamps metadata.model on the subagent row (issue #185), so a tiered pipeline (Opus orchestrator + Sonnet/Haiku subagents) is priced per real model rather than entirely at the orchestrator's rate; the parent-model bucket is skipped to avoid colliding with the main-transcript token writer's compaction baseline logic. Session reactivation on resume (including Stop/SubagentStop reactivation for imported completed/abandoned sessions), orphaned-session cleanup uses DASHBOARD_STALE_MINUTES (default 180). Uses a shared TranscriptCache instance (server/lib/transcript-cache.js) for extraction of tokens, API errors, turn durations, thinking blocks, and usage extras — stat-based caching with incremental byte-offset reads avoids re-reading entire JSONL files on every event. Detects compaction via isCompactSummary in JSONL transcripts and creates compaction agents + events (deduplicated by uuid). Token baselines (baseline_* columns) preserve pre-compaction totals so no usage is lost. Cache entries are evicted on SessionEnd. SessionEnd preserves error state — but only when the error is still unrecovered at the transcript tail (isErrorAtTail: latest API error with no successful turn after it); a transient error the CLI retried past finalizes as completed instead of freezing in a stale error. Error recovery: UserPromptSubmit and PreToolUse recover a session from error; additionally the 15 s watchdog now scans error sessions and self-heals one back to active when its transcript has progressed past the last API error (isErrorAtTail false) — closing the gap where a transient API error left an imported or sweep-monitored session (no live recovery hook) pinned in error forever. Session naming: on every event, syncs sessions.name from the transcript title surfaced by TranscriptCache and broadcasts session_updated — an explicit custom-title (/rename, claude -n, picker Ctrl+R) always wins, an ai-title (auto / plan-accept) only fills a placeholder/auto name (Session <id8> or a cwd-folder import name) so a user-chosen name is never clobbered. When neither title exists, the session's first user prompt (surfaced by TranscriptCache as firstUserMessage; tool-result / meta / slash-command plumbing entries skipped) fills the placeholder session name plus the main agent's placeholder name and empty task (issue #201) — a later ai-title can still replace a descriptor-filled name, and the agent fill passes the in-flight current_tool through (the shared updateAgent statement writes that column verbatim) so it is never wiped mid-turn. The guarded updateSessionName no-ops on the unchanged case, so the broadcast path stays quiet; the 15 s error-watchdog runs the same sync for idle sessions that fire no hook after a rename. Dead-session liveness reap: the same watchdog completes any active session whose cwd has no running claude CLI process (probe via lib/session-liveness.js) — recovering a SessionEnd lost while the dashboard was down (e.g. Ctrl+C) that previously left the session in Waiting until the 3 h stale sweep; watchdog ticks are gated on the transcript mtime (fallback updated_at when no transcript exists) being older than DASHBOARD_LIVENESS_IDLE_SECONDS (default 60 s); the boot passes — immediately at startup and again ~5 s later (post-import) — skip the gate so a session quit moments before launch clears at once, disabled via DASHBOARD_LIVENESS_PROBE=0 / on Windows / in containers, and a false completion self-heals through hook reactivation. Sessions whose cwd is not POSIX-absolute (household-hook-forwarded from another machine, e.g. a Windows D:\… path a local /proc/lsof scan can never match) are skipped by the reap — so a mixed local + forwarded deployment stays correct without disabling the whole probe. Remote Data Source sessions (sessions.source ≠ local) are excluded from the reap, the error/interrupt watchdog scan, and both stale sweeps (all gated on source = 'local'): their POSIX-absolute cwd lives on another machine, so local process/clock heuristics would wrongly terminate a running remote session — their status is reconciled from the SSH mirror by remote-sync.js instead
routes/sessions.js	Standard CRUD with pagination. GET includes agent count via LEFT JOIN. POST is idempotent on session ID. GET /:id/transcript also surfaces custom-title lines as synthetic session_event (rename) messages — deduped, with ai-title excluded — so TUI-only /rename (which writes no user/assistant turn) is still visible in the conversation viewer. It also surfaces system/local_command lines: newer Claude Code builds write a local slash command's invocation and captured output (<command-name>, <local-command-stdout>/stderr) as system/local_command entries with the TUI markup in a top-level content string (older builds used user messages), so the route re-emits those as user-side text and the client's tuiSegments parser renders the command pill + its output (e.g. /color → a /color pill plus "Session color set to: cyan"). Content-less local_command lines (e.g. /clear) and every other system subtype (turn_duration, stop_hook_summary, …) are dropped as noise
routes/agents.js	CRUD with status/session_id filtering. PATCH broadcasts agent_updated. Agent-list responses (GET /api/agents, GET /api/sessions/:id/agents) attach a per-agent cost via pricing.attachAgentCosts — each subagent's OWN cost, computed from its metadata.tokens at current rates (main agents get 0; their cost is the session total), so a subagent card shows only what that subagent spent rather than the session total
routes/events.js	Read-only event listing with session_id filter and pagination
routes/stats.js	Single aggregate query returning total/active counts + status distributions
routes/metrics.js	Prometheus / OpenMetrics text-exposition endpoint (GET /api/metrics) — re-exposes the dashboard's live counters (sessions/agents by status, event + token totals, connected WebSocket clients, configured remote sources, process uptime/RSS, build version) in the v0.0.4 text format for scraping into Prometheus / Grafana. Read-only; reads the same db.js prepared statements the REST API uses, so numbers match the UI. Status series are enumerated so a gauge never drops out at zero. Mounted under /api, so it sits behind the Host-header (DNS-rebinding) guard and the optional DASHBOARD_TOKEN guard — a non-loopback scraper needs DASHBOARD_ALLOWED_HOSTS (+ token if set). A turnkey Prometheus + Grafana stack with four auto-provisioned dashboards lives in monitoring/ (npm run monitoring:up or npm run docker:full:up)
monitoring/	Optional npm-managed or Docker Compose Prometheus + Grafana stack that scrapes GET /api/metrics. Ships four Grafana dashboards (ccam-overview, ccam-sessions-agents, ccam-tokens-events, ccam-platform), recording rules (prometheus/ccam-rules.yml), a Prometheus 3.x-compatible static HTML console (prometheus/consoles/index.html), and lifecycle scripts (monitoring:install, monitoring:up, monitoring:verify). See monitoring/README.md
routes/analytics.js	Extended analytics — token totals, tool usage counts, daily event/session trends, agent type distribution. The client-side analytics heatmap grid is aligned to a Sunday start for correct day-of-week positioning
routes/pricing.js	Model pricing CRUD (list/upsert/delete) and per-session / global cost calculation with pattern-based model matching. PUT /api/pricing upserts a rule and accepts optional time-limited introductory rates (intro_*_per_mtok + intro_until): usage on/before the cutoff date prices at the intro rate, after it at the standard rate — the calculator picks the effective rate per usage day (ratesForBucket), so a promo like Sonnet 5's launch discount is correct before AND after the cutoff, retroactively. Intro columns are written only when the caller sends them (a standard-rate edit never disturbs a promo). Cost is computed per token bucket — keyed by (model, speed, inference_geo, service_tier) — applying fast-mode premium, US data-residency (1.1x), and Batch (0.5x) modifiers, the 5m/1h cache-write split, plus server-tool surcharges (web search $10/1k; code execution estimated by container-time with the monthly free-hours allowance; web fetch free). attachAgentCosts/agentOwnCost reuse the same calculator to price each agent's metadata.tokens for the per-agent cost on agent-list responses. Feature rates + modifier math live in lib/pricing-constants.js; usage normalization in lib/token-usage.js
routes/settings.js	System info (DB size, hook status, server uptime, transcript cache stats), data export as one versioned JSON bundle and matching import/restore (POST /api/settings/import via server/lib/data-transfer.js — idempotent, session-atomic, non-destructive; consolidates machines), session cleanup (abandon stale, purge old), clear all data (including the fired-alert feed and webhook delivery log; alert rules and webhook targets are preserved as user configuration), reset pricing, reinstall hooks
routes/alerts.js	HTTP surface for the rules-based alerting engine: alert-rule CRUD (GET/POST /api/alerts/rules, PATCH/DELETE /api/alerts/rules/:id — rule_type is immutable after creation, config re-validated against the stored type on PATCH), the fired-alert feed (GET /api/alerts with ?unacked=true + pagination, response carries total and unacked counts), and acknowledgement (POST /api/alerts/:id/ack, POST /api/alerts/ack-all, broadcasting alert_updated). Every rule mutation calls invalidateRuleCache() so the evaluation engine picks up changes immediately
lib/alerts.js	Rule evaluation engine for the alerting feature. Four rule types: event_pattern (match event_type / tool_name / summary_contains, optionally requiring ≥ count matching events within window_minutes — counted via a dynamically built, statement-cached SQL query), token_threshold (session total tokens ≥ total_tokens, only evaluated on token-bearing events: PostToolUse / Stop / SubagentStop / SessionEnd), inactivity (active session whose updated_at — bumped on every ingested event — is older than minutes), and status_duration (agent stuck in working/waiting with no activity for minutes, joined against active sessions). Event-driven types run via evaluateEvent() called from routes/hooks.js after the ingest transaction commits and the HTTP response is sent — alerting can never slow down or fail hook ingestion, and evaluateEvent is itself fully try/catch-guarded per rule. Time-based types run via sweepTimeRules() on a 60 s unref'd interval (same pattern as the hooks watchdog). fireAlert() applies per-(rule, session, agent) cooldown dedup (cooldown_seconds, default 300) by checking the most recent alert_events row for the scope, then persists and broadcasts alert_triggered. Enabled rules are cached in memory (hook ingest is hot) and invalidated on every CRUD mutation. validateRuleConfig() normalizes + validates type-specific config and is shared with the routes. After persisting and broadcasting a fired alert, fireAlert() hands it to lib/webhooks.js dispatchAlert() fire-and-forget (lazy-required to keep the module graph acyclic) — webhook delivery never blocks or fails alert firing
routes/webhooks.js	HTTP surface for universal webhook targets: target CRUD (GET/POST /api/webhooks, PATCH/DELETE /api/webhooks/:id — type is immutable after creation), a redacted provider catalog (GET /api/webhooks/providers, drives the UI form), a synchronous test probe (POST /api/webhooks/:id/test — always 200, the ok flag carries the downstream delivery result), and a per-target delivery log (GET /api/webhooks/:id/deliveries). Validation is registry-driven: required URL (per provider), per-provider config fields, https enforcement, generic-family secret/headers. Security: target URLs are masked (host + last 4 chars) and secret config fields + custom-header values are redacted in every response — full URLs, signing secrets, and credentials (routing keys, api keys, bot tokens) are stored server-side and never leave the server. PATCH uses "set-flag" semantics (omit url/secret/headers/config to leave unchanged); config is merged over the existing config so one field can change without re-sending secrets. Every mutation calls invalidateWebhookCache()
lib/webhook-providers.js	Declarative registry of the 14 first-class providers (+ generic). Each entry declares a family (chat / api / generic), a payload formatter, URL resolution (urlFrom(config) for Telegram/Opsgenie that derive the endpoint, defaultUrl for PagerDuty, or a user-supplied URL), optional authFrom(config) headers (Opsgenie GenieKey), and the credential fields the UI renders + the route validates. Formatters emit each platform's native body: Slack Block Kit, Discord embed, Teams Adaptive Card wrapped in the Power Automate Workflows { type: "message", attachments: [...] } envelope (the legacy O365-connector MessageCard transport was retired May 2026), Google Chat text, Mattermost/Rocket.Chat Slack-style attachments, Telegram sendMessage (HTML), PagerDuty Events API v2 (with dedup_key), Opsgenie Alert API, Splunk On-Call/VictorOps, and the generic { event, alert } envelope. A provider may also declare verifyResponse(body) to veto a 2xx that actually signals failure (Splunk On-Call returns 200 with result:"failure"). publicProviders() returns the redacted catalog. Adding a provider = one registry entry + a formatter — no route or delivery changes
lib/webhooks.js	Universal webhook delivery engine driven by the provider registry. buildRequest() resolves the URL, formats the provider-native payload, and assembles headers (provider auth headers + generic-family custom headers + optional HMAC-SHA256 signature via X-Webhook-Signature / X-Webhook-Timestamp). dispatchAlert() fans a fired alert out to every enabled, in-scope target (optional per-rule scoping via rule_ids); each deliver() POSTs with an AbortController timeout and bounded retry/backoff (retries transport errors / 429 / 5xx, never other 4xx) and records the attempt-chain outcome in webhook_deliveries (pruned to the newest 2000 rows). Delivery is detached and fully fail-safe — it never throws into the alert path. Enabled targets are cached like alert rules; tunables (WEBHOOK_TIMEOUT_MS, WEBHOOK_MAX_ATTEMPTS, WEBHOOK_RETRY_BASE_MS) are env-overridable. sendTest() awaits a synthetic delivery for the test endpoint
routes/workflows.js	Aggregate workflow visualization data (agent orchestration graphs, tool transition flows, collaboration networks, workflow pattern detection, model delegation, error propagation, concurrency timelines, session complexity metrics, compaction impact). Accepts ?status=active|completed query parameter to filter all data by session status. Per-session drill-in endpoint with agent tree, tool timeline, and event details
lib/transcript-cache.js	Stat-based JSONL transcript cache with incremental byte-offset reads. Shared between hooks.js (token extraction on every event) and the periodic compaction scanner (index.js). Extracts tokens, compaction entries, API errors (isApiErrorMessage + raw error responses), turn durations (system subtype turn_duration), thinking block counts, usage extras (service_tier, speed, inference_geo), user-interrupt markers (the transcript [Request interrupted by user] entry / interruptedMessageId field — surfaced as pendingInterrupt, computed from transcript ordering: latest interrupt vs latest real turn activity, both on Claude Code's clock), and the latest session title — custom-title (/rename, claude -n, picker Ctrl+R) and ai-title (auto / plan-accept), append-only so the last value wins, carried through both full and incremental reads — plus the session's first user prompt (firstUserMessage: tool-result, meta/caveat, slash-command plumbing, compact-summary, and interrupt entries skipped; whitespace-collapsed, capped at 500 chars; first value wins across incremental reads), used as a fallback descriptor for placeholder-named sessions/agents. Uses (path, mtime, size) cache key — unchanged files return cached results instantly, grown files only parse new bytes, shrunk files (compaction) trigger full re-read. Each cache entry stores only {mtimeMs, size, bytesRead, result} — the previous shape that duplicated every growable array at both the top level and inside result is gone, halving steady-state memory per entry. Per-entry growable arrays (turnDurations, errors, compaction.entries, usageExtras.*) are bounded to TRANSCRIPT_CACHE_MAX_ARRAY_LEN (default 1000, tail-kept) — older items remain in the events table thanks to hook dedup, so the cap only affects the in-memory view. Trimming runs both during parse (when an array reaches 2 * MAX_ARRAY_LEN, amortized O(N)) and at finalize, so even a fresh full-file parse on a multi-day session cannot accumulate an unbounded transient before returning. Chunked sync byte-stream reader (_streamRange, 4 MiB chunks split on 0x0A bytes — safe across UTF-8 multibyte sequences — with a growable per-line byte buffer capped at 64 MiB) replaces the previous readFileSync("utf8") so transcripts larger than V8's max JS string length (~512 MiB on 64-bit Node 20) parse without aborting Node with FATAL ERROR: v8::ToLocalChecked Empty MaybeLocal. Both full and incremental reads share the same line-level state machine (_initParseState / _consumeLine / _finalizeState). LRU eviction caps at 200 entries. Entries evicted on SessionEnd and abandoned session cleanup
lib/session-liveness.js	Process-liveness probe for the watchdog's dead-session reap. probeLiveCwds() enumerates running claude CLI processes (ps -Ao pid=,args=, then lsof -a -p <pids> -d cwd -Fn on macOS or /proc/<pid>/cwd on Linux) and returns the set of their working directories; isClaudeCommand() matches the bare binary and node/bun-launched shims while rejecting lookalikes (claude-mem, Claude.app). Fail-safe by contract: returns available: false (callers must change nothing) on Windows, inside containers (reuses isInsideContainer from scripts/install-hooks.js — host processes are invisible there, so an empty list would lie), on ps/lsof failure, or when DASHBOARD_LIVENESS_PROBE=0
bin/ccam.js	Dependency-free umbrella CLI (ccam <command>) exposing the full dashboard surface in the terminal: monitoring (health / stats / kanban / tail via short-interval event polling), data browsing (sessions, per-session detail with an indented agent tree + cost + recent events, agents, events), insights (analytics, workflow intelligence, dynamic Workflow-tool runs, per-model cost), alerts + rules + webhook test probes, pricing CRUD, imports (rescan / scan-path), and administration (doctor, info, export, cleanup, reinstall-hooks, clear-data). Linked globally by npm run setup via a fail-soft npm link (link-cli script). Discovers the live server through server/lib/server-info.js (~/.claude/.agent-dashboard.json, PID-liveness-checked) with CLAUDE_DASHBOARD_PORT / DASHBOARD_PORT env overrides and a 4820 fallback; renders a full terminal UI — box-drawn width-fitted tables with right-aligned numeric columns, status icons, inline bar charts (stats / analytics / cost), ├─/└─ agent trees, and a TTY spinner for start — whose ANSI styling degrades to plain text when piped (--no-color / NO_COLOR / FORCE_COLOR / CCAM_COLOR respected); the one destructive command (clear-data) refuses to run without --yes. Server lifecycle: ccam status shows a ●/○ up/down indicator and ccam start boots a detached production server (waits for /api/health, logs to data/ccam-server.log). ccam repl (aliases shell / i) opens an interactive shell — a readline prompt with tab-completion (commands / subcommands / flags), persisted arrow-key history (data/.ccam_repl_history), and a live server-status prompt; each entered line runs as a short-lived child ccam process (via runCommand dispatch), so an offline refusal or a blocking tail cannot take the shell down, and piped input runs each line in order then exits at EOF. When the server is down, read-only commands (sessions / session / agents / events / kanban / stats / pricing list / alerts list / rules / export / doctor) fall back to direct SQLite reads of data/dashboard.db under a ⚠ Offline-mode banner — the connection is opened without SQLite readonly mode so a live WAL stays visible, and is SELECT-only by construction — while server-only commands (tail, analytics, workflows, runs, cost, mutations) refuse with the specific reason
scripts/import-history.js	Batch history importer used by (a) server startup auto-import, (b) the /api/import/* routes, (c) the import-history CLI, and (d) live SubagentStop ingestion via the exported scanAndImportSubagents(dbModule, sessionId, transcriptPath). Exposes importAllSessions(dbModule) for the default ~/.claude/projects tree, syncDefaultProjects(dbModule, {mtimeCache}) (the incremental, mtime-fingerprinted re-sweep that backs the continuous background sync — parses only new/changed files and reports [{sessionId, isNew}]), and the generalized importFromDirectory(dbModule, rootDir, {onProgress}) which walks any directory recursively, classifies each .jsonl as session vs subagent (with findSessionSubagents probing both <proj>/<sid>/subagents/* and <proj>/subagents/<sid>/* layouts), and funnels everything through the shared parseSessionFile + importSession pipeline. The durable transcript snapshot (snapshotTranscript) additionally preserves nested Workflow-tool inner-agent transcripts (subagents/workflows/<runId>/agent-*.jsonl) via the separate findSessionWorkflowSubagents probe — mirroring the run subpath so the read route resolves the snapshot identically to the live file, without pulling those nested agents into the flat sub-agent import (no double-count). After each batch imports, importAllSessions / importFromDirectory also call ingestWorkflowsForSession (from server/lib/workflow-ingest.js) per session — outside the SQLite transaction, since the ingest is async — so a Workflow-tool run whose journal never reached a live server (a headless claude -p run, a CI job, or an HPC/cluster node emits no hooks) still links its inner agents to their run_id on a plain ccam import rescan / ccam import path, instead of leaving them orphaned (workflow_run_id = NULL) with the run stuck at 1 agent — see "Workflow-Tool Run Ingestion". parseSubagentFile extracts ordered toolEvents (tool_use + tool_result paired by tool_use_id) so importSubagentFromJsonl can emit per-tool PreToolUse + PostToolUse rows under each subagent's own agent_id. The importer dedups against live hook-created subagent rows via findLiveSubagentForJsonl (session + subagent_type + start-time within 30 s) so backfill never produces parallel <sid>-jsonl-* rows. It also skips importSubagents entirely when subagent transcripts exist — the main-transcript Agent-block rows (<sid>-subagent-N) and the transcript rows (<sid>-jsonl-*) would otherwise both be created and only deduped by a fragile type+timing match, doubling every subagent; when transcripts are present the richer -jsonl- rows are authoritative and the -subagent-N fallback runs only when there are none. importSession now also persists transcript_path on the session row (via setSessionTranscriptPath) so the abandon sweep, compaction scanner, and per-agent cost backfill can locate the transcript later, and stamps each subagent's own token buckets into metadata.tokens (used for per-agent cost). backfillSubagentTokenMetadata (a deferred, self-limiting startup pass) fills metadata.tokens on subagents that predate per-agent cost, deriving the transcript path from <projectsDir>/<slug>/<sid>.jsonl when transcript_path is null and covering both subagent-dir layouts — metadata-only, so it never touches session token_usage. classifyJsonl treats any file under a subagents/ ancestor at any depth (including the subagents/workflows/<runId>/ tree) as a subagent, so workflow inner-agent transcripts are never misimported as top-level sessions. Nested-subagent hierarchy is rebuilt by reconcileSubagentParents: every subagent is inserted flat under the main agent (no single hook/JSONL carries the spawner id), then parseSubagentFile also returns spawnedChildren — the child agent ids named on each Task tool result (toolUseResult.agentId) — which are inverted to a child→parent map and used to repoint parent_agent_id (via the setAgentParent statement) so a subagent that spawns its own subagents nests under its true spawner instead of collapsing flat under main; any subagent no other subagent claims stays under main. It resolves both the child and parent to their live-or-jsonl DB id (mirroring importSubagentFromJsonl), so it also corrects the live hook heuristic's guesses once the transcripts land. Idempotent and additive (only rewrites parent_agent_id), it runs in all three group-import paths (importSession ×2, live scanAndImportSubagents); scanAndImportSubagents returns a reparented count alongside created. Re-import is fully incremental: for each existing session a per-event-type high-water mark (MAX(created_at) GROUP BY event_type) is read up-front and only JSONL entries with ts > cutoff[type] are inserted for Stop / PostToolUse / TurnDuration / ToolError — so long-running sessions whose transcripts grow across multiple days continue to receive new events on every re-run instead of being blocked by the old "if zero of type X then dump all" check. sessions.ended_at is rolled forward to the JSONL's last activity when it surpasses the stored value, and metadata.user_messages / assistant_messages / turn_count are refreshed on every pass. parseSessionFile also captures the transcript title (custom-title / ai-title) and importSession prefers it for sessions.name over the cwd-folder fallback, backfilling existing auto/placeholder names on re-import (same precedence as the live hook sync). Other idempotency keys are unchanged: data LIKE '%"tool_use_id":"X"%' skips any tool event already inserted, compaction agents/events dedup by uuid, API errors dedup by summary, and baseline_* columns preserve pre-compaction token totals. Token totals, per-model cost, compactions, subagents, tool events, API errors, and turn durations are identical to live ingestion. Creates APIError, TurnDuration, and ToolError event types during import; subagent tool events carry imported: true, source: "subagent_jsonl" in their data payload so analytics can distinguish backfilled rows when needed
server/routes/import.js	Express router for the Import History feature. Three endpoints funnel into the same pipeline: POST /api/import/rescan (default projects dir), POST /api/import/scan-path (arbitrary absolute dir with ~ expansion), POST /api/import/upload (multer multipart accepting .jsonl, .meta.json, .zip, .tar, .tar.gz, .tgz, .gz). GET /api/import/guide returns OS-aware instructions + archive command + default-dir stats. Each request uses a per-request temp dir (req._ccamUploadDir for multer staging, a separate workDir for extraction) that is reclaimed in finally. Progress is broadcast as import.progress websocket messages throttled at ~150 ms. Limits configurable via CCAM_IMPORT_MAX_BYTES / CCAM_IMPORT_MAX_FILES
server/lib/data-transfer.js	Full-dataset export/import ("backup / restore"). buildExportBundle(db, stmts) serializes every user-owned table (sessions, agents, events, token_usage, workflows, dashboard_runs, alert_rules, model_pricing) into one versioned JSON bundle (format: "ccam-export"); machine-bound/secret tables (push_subscriptions, webhook_targets/deliveries, alert_events) are excluded. importExportBundle(db, bundle) restores it session-atomically inside one transaction with defer_foreign_keys ON: a session already present (by UUID) is skipped WHOLE (with its agents/events/token_usage/workflows) so re-import and cross-machine merges never duplicate or clobber; events are re-inserted without their non-portable autoincrement id; config rows use INSERT OR IGNORE on their natural key. Backs GET/POST /api/settings/{export,import} and ccam import-data
server/lib/archive.js	Safe archive extraction: .zip via adm-zip, .tar/.tar.gz/.tgz via tar, plain .gz via zlib in streaming mode. Every entry is validated through safeJoin which rejects absolute paths and .. traversal before any bytes are written. Enforces a hard extraction cap (MAX_EXTRACT_BYTES, default 4 GB, tunable via CCAM_IMPORT_MAX_EXTRACT_BYTES) with ExtractionLimitError surfaced as HTTP 413 from the upload route — defense against zip/tar/gzip bombs. Also provides detectKind for filename-based dispatch and mkTempDir/rmTempDir helpers
server/lib/remote-sync.js	Remote Data Sources — live remote/multi-machine data collection over SSH. Mirrors the remote's ~/.claude/projects via scp (or wsl.exe + tar for WSL-hosted Claude on Windows SSH) into a sandboxed per-source staging dir under the data dir, then feeds it through the same importer used for local history (importFromDirectory from scripts/import-history.js) and tags every imported session with the source id (sessions.source). Also runs the connectivity probe behind the test route. Auth defers entirely to the host SSH stack (ssh-agent / ~/.ssh/config / identity file) — no secrets are ever stored; every shell-out uses execFile/spawn argument arrays (never a shell string), and StrictHostKeyChecking is left at its SSH default. Background poller DASHBOARD_REMOTE_SYNC_MS (default 15000); add/re-enable triggers immediate pull. Sync timeout DASHBOARD_REMOTE_SYNC_TIMEOUT_MS (default 600000); connectivity-test timeout DASHBOARD_REMOTE_TEST_TIMEOUT_MS (default 15000). Broadcasts remote_source.status, remote_data.updated, and per-session session_created/session_updated on successful sync. After each pull, reconcileRemoteSessionStatus sets each source session's live status from the mirror — newest JSONL event timestamp within DASHBOARD_REMOTE_ACTIVE_WINDOW_MS (default 600000 = 10 min) ⇒ active, otherwise completed. Remote sessions get no live hooks and are excluded from every local liveness/stale heuristic (all gated on source = 'local'), so this reconciliation is the sole owner of their active/completed lifecycle
server/routes/remote-sources.js	HTTP surface for Remote Data Sources: GET /api/remote-sources (list), POST /api/remote-sources (create), PATCH /api/remote-sources/:id, DELETE /api/remote-sources/:id (?purge=true also deletes that source's imported sessions), POST /api/remote-sources/:id/test (SSH connectivity probe), and POST /api/remote-sources/:id/sync (on-demand pull). Delegates the pull/validation to remote-sync.js; broadcasts remote_source.status on every transition
server/lib/source-filter.js	Parses the optional ?sources= query param (comma-separated source ids) into SQL predicates + bind params, shared by the data endpoints (GET /api/sessions, /api/events, /api/agents, /api/stats, /api/analytics) so a client data-scope selection narrows every query consistently. No filter → the existing unscoped queries run unchanged
server/lib/scoped-stats.js	Source-scoped variants of the stats/analytics aggregates, used only when a ?sources= scope filter is active — the unscoped fast paths in routes/stats.js / routes/analytics.js are untouched when no scope is set
lib/cc-discovery.js	Read-only discovery of every Claude Code config surface for the Config Explorer page. Pure file reads; never writes. Surfaces: skills (<root>/skills/<name>/SKILL.md), subagents (<root>/agents/*.md), slash commands (<root>/commands/*.md), output styles (<root>/output-styles/*.md), plugins (<CLAUDE_HOME>/plugins/installed_plugins.json joined with enabledPlugins in settings + per-plugin contributes count by scanning the install dir + plugin.json metadata), marketplaces (known_marketplaces.json enriched with each marketplace.json), MCP servers (top-level + per-project from ~/.claude.json), hooks (across user / project / project-local settings.json), keybindings (<CLAUDE_HOME>/keybindings.json), statusline config + statusline.py / statusline-command.sh content, hook scripts dir (<CLAUDE_HOME>/hooks/), settings (with secret-key redaction matching /token|secret|password|api[_-]?key|auth/i), memory (CLAUDE.md at user + project plus the per-project file-based auto-memory store — every *.md under ~/.claude/projects/<slug>/memory/, returned as scope:"auto-memory" items carrying project, name, isIndex, and parsed frontmatter, so a MEMORY.md index and one file per remembered fact, often 100+, all surface). Path containment via isUnder() — every read must resolve under CLAUDE_HOME, project .claude/, or be a project CLAUDE.md. 256 KB read cap. Minimal YAML frontmatter parser handles key: value + quoted strings + indented continuation lines
lib/cc-mutate.js	Create / overwrite / delete for the low-risk text-file surfaces only (skills, subagents, slash commands, output styles, memory — including the per-project file-based auto-memory store, mutated via scope: "auto-memory", type: "auto-memory", project, name, with its backups landing in <memory-dir>/.cc-config-backups/auto-memory/), plus writeKeybindings() for the structured keybindings.json editor (read-modify-write that preserves top-level metadata, rejects duplicate contexts/keys, and backs up to <CLAUDE_HOME>/cc-config-backups/keybindings/). Plugins, MCP, hooks-in-settings, and settings.json files are NEVER written from here — they have concurrent-write races with the live Claude Code CLI. Every mutation creates a timestamped backup at <root>/cc-config-backups/<type>/<base>.<ISO>.bak[.dir] BEFORE the change — backups land outside the directories Claude Code scans, so a deleted skill cannot resurface as a backup-named one. Writes are atomic: temp file in same dir → fsync → renameSync. Tmp removed on every failure path. Skill dirs are backed up whole (preserving bundled assets) before recursive removal. Strict name regex (^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$), 256 KB content cap, double-checked path containment via isUnder()
routes/cc-config.js	HTTP surface for the Claude Config Explorer. Read endpoints for every surface (skills, agents, commands, output-styles, plugins, marketplaces, mcp, hooks, hook-scripts, keybindings, statusline, settings, memory, file, overview), plus mutation endpoints (PUT /file, DELETE /file, and a structured PUT /keybindings) that delegate to cc-mutate.js, plus a GET /backups listing for the recovery modal. After every successful PUT/DELETE the route broadcasts cc_config_changed over the WebSocket so any open /cc-config tab refetches without polling. All errors return structured {error: {code, message}} shapes mapped to 400/404/413/500 statuses
lib/cc-watcher.js	Best-effort fs.watch over ~/.claude/ (recursive where the platform / Node version honors it — macOS / Windows always; Linux from Node 20) plus ~/.claude.json. Coalesces bursts at 500 ms and broadcasts cc_config_changed with { source: "fs", paths: [...] } so the Config Explorer picks up changes from external tools (CLI installs a plugin, manual settings.json edits, dropping a new skill) without a manual refresh. Started from server/index.js after the HTTP server boots; failures are caught and logged so a flaky watcher can't take the server down
lib/stream-json-parser.js	Newline-delimited JSON line buffer for parsing claude --output-format stream-json output. Reassembles arbitrarily chunked stdout into discrete envelopes. Robust: malformed lines are reported via an onError callback but never throw
lib/run-spawner.js	Spawns and supervises claude subprocesses for the Run page. Two modes: headless (-p "<prompt>" in argv, stdin closed, exits after one turn) and conversation (--input-format stream-json, prompt + follow-ups piped over stdin, multi-turn). Conversation mode also supports resumeSessionId → --resume <id>; an empty prompt is permitted in this case (the spawner skips the initial stdin write so claude idles on the resumed transcript until the user POSTs a follow-up via /run/:id/message). The argv builder also passes through an optional effort (low/medium/high) → --effort. Output is always --output-format stream-json --verbose --include-partial-messages so the parser yields character-level deltas (stream_event envelopes) the UI can render token-by-token; each envelope is broadcast as run_stream over the existing WebSocket. Status transitions broadcast as run_status. A failed spawn records an actual-exit timestamp too: no child started, so lane teardown can safely proceed instead of waiting for a nonexistent exit event. SIGTERM escalation checks that timestamp rather than Node's delivery-acknowledgement child.killed, so a child that ignores SIGTERM still receives SIGKILL after five seconds. Concurrency is effectively uncapped (default ceiling 10000 — matches the terminal TUI which has no cap; the cap is sanity-only to prevent fork-bomb footguns from a buggy client; override with RUN_MAX_CONCURRENT, NaN-safe). Per-handle bounded envelope log (cap 500) lets late-attaching clients replay history via ?envelopes=1. The Run page additionally reconciles this in-memory log against the session's on-disk JSONL transcript on every attach (incl. clicking Resume / View on a row) — when the transcript has more user/assistant messages than the spawner saw (e.g., a resumed run whose prior history never traversed stdout), it supersedes; otherwise the spawner's log wins (it has stream_event deltas the transcript doesn't carry until each turn finalizes). This is what makes leaving a resumed run and coming back show the same chat the user saw initially. Completed handles reaped after 5 min; full transcripts persist via the normal hook ingestion pipeline because every spawned claude fires hooks like any other CLI session
routes/run.js	HTTP surface for the Run feature. Same-origin guard on every route — browser requests must come from a localhost-ish Origin (localhost, 127.0.0.1, ::1, 0.0.0.0); missing-Origin (curl/CLI) requests pass. When DASHBOARD_TOKEN is configured it is also required on these routes (same as the rest of /api/*). cwd sanitization: must be absolute and exist as a directory. GET / lists handles + concurrency state. GET /binary probes whether claude is on PATH. GET /cwds suggests cwds (dashboard + home + recent from sessions table). GET /files?cwd=&q= powers the Run page's @-file autocomplete: scoped fuzzy search inside cwd skipping node_modules, .git, dist, build, .next, .cache, coverage, vendor, etc., capped result count, ranked by basename match. POST / spawns (accepts effort in body). POST /:id/message sends a follow-up turn. GET /:id returns the handle; ?envelopes=1 includes the in-memory envelope log for re-attach. DELETE /:id SIGTERMs (escalates to SIGKILL after 5 s)
routes/lanes.js	Durable-lane API. POST /api/lanes/worktree, PATCH /api/lanes/:id, destructive actions, and DELETE /api/lanes/:id use the Run route's same-origin guard. Worktree provisioning validates an absolute source git repository, persists a managed lane as provisioning, returns 202, then uses the per-lane lock to resolve the base and add the worktree. Completion broadcasts the existing lane_update payload as idle; a git failure leaves a row that the non-destructive delete route can forget. GET /api/lanes/:id/preflight?action=reset|remove|purge produces counted confirmation facts. Confirmed POST /:id/{reset,remove,purge} actions require a complete expect, run under the same lock, kill a recorded run and wait for the spawner's actual child-exit timestamp (or return 500 ERUNTIMEOUT before git), clear run_id, reject changed facts with 409 ESTALE including expected/current diagnostics, and require force for unpushed managed reset/remove work. Reset and managed removal call the worktree's independent managed-kind, realpath-within-LANES_ROOT, and listed-worktree guard; adopted reset is refused, while adopted remove only forgets its row and never modifies its directory, and a managed lane whose directory was deleted by hand takes a prune path that still enforces the managed-kind and inside-LANES_ROOT checks. start returns 409 ERUNLIVE rather than overwriting a live run_id and orphaning its child. kind, source_repo, slug, base_branch, slot and ports are not patchable — provisioning writes them through lanesLib.setProvisioningFacts. Worktree provisioning also runs lane-runtime.js:provisionLane (A2) when the repo declares a .ccam/profile — seed .env, bootstrap, create the database, migrate, seed — before the lane reports idle; reset/remove likewise call resetLaneData/removeLaneData, with reset accepting a body keepDb: true to skip the whole drop-recreate-migrate-reseed block. The runtime routes (GET /:id/runtime, POST /:id/up, POST /:id/down, POST /:id/hook/:name, GET /:id/logs/:svc) are registered before the /:id/:action catch-all so up/down are not swallowed as unknown actions, and are deliberately kept out of it: that catch-all drives a lane's Claude run, these drive the application the lane is working on.
lib/ports.js	TCP probing for runtime allocation. isListening(port) connects rather than binds (binding races with the hook about to bind, and says nothing about a listener held by another user); a connect timeout counts as occupied. listenerPids(port) shells to lsof, falls back to ss, and returns [] with a one-time warning when neither exists — a missing tool must never fail a lane operation
lib/lane-slots.js	Slot and port allocation — the numbering Shipyard gets free from fixed lane1..lane9 directories and CCAM, keyed by cwd, must allocate. allocateSlot takes the lowest free of LANE_MAX_SLOTS (default 9) under the per-lane lock, with a partial unique index on lanes.slot as the backstop; allocation is lazy, so a lane that is only watched never consumes one. releaseSlot runs on remove but never on reset (moving a lane's ports mid-feature is a silent failure, not a fresh start). resolvePorts prefers PORT_BASE_<name> + slot, then steps +100 at a time so the last digit still reads as the slot, skipping anything listening, recorded by another lane, or already taken in the same boot. slotDirs puts run/log state under LANES_ROOT/.state/lane<slot>/ — outside the worktree, because reset's git clean -fd would otherwise sweep live pid files. dbName/dataFacts (A2) derive the same kind of slot-based fact one layer up: database name, DATABASE_URL/TEST_DATABASE_URL, a Redis logical index, and the upload directory — each null when its owning profile declaration (DB_PREFIX, REDIS, UPLOAD_SUBDIR) is absent
lib/lane-profile.js	The stack seam. Resolves <repo>/.ccam/profile/ from the lane's own working copy first (a branch that edits its boot command must boot with it), the source repo second. profile.env is parsed, not sourced — $(…) stays literal, because sourcing repo shell into the dashboard process would be a code-execution path. runHook spawns bash <hook> with an argv array through a wrapper that export -fs harness_spawn/die, exports Shipyard's env contract verbatim (LANE is the slot, plus <NAME>_PORT per declared port, plus A2's DB_NAME/DATABASE_URL/TEST_DATABASE_URL/PG_HOST/PG_PORT/PG_USER/REDIS_URL/REDIS_HOST/REDIS_PORT/UPLOAD_DIR when their profile declaration is present) so its profiles port unchanged, scrubs GIT_* exactly as worktree.js:git() does, redacts any secrets.js password from its output before it reaches the log file or the lane_hook_output broadcast, and streams the rest to both $LOG_DIR/<hook>.log and that broadcast. Hook names come from a fixed allowlist, never from a request
lib/lane-runtime.js	Lane stack lifecycle. upLane runs boot then health (never bootstrap — that belongs to provision/reset) and leaves processes running on a failed health check, because their logs are the evidence. Before boot it also repairs .env, ensures the database exists, migrates every boot, and seeds only the boot that created the database (A2). downLane kills each recorded pid tree bottom-up (a parent killed first reparents children to init) and only sweeps port listeners when a pid file existed — an unconditional sweep would kill a server the user started on a lane's stale port. runtimeFacts computes liveness on every read from pid files and probes rather than caching it (plus the database name/Redis index, never a connection string), which is both correct when a process dies unobserved and why adopting a stack after a dashboard restart needs no code at all. provisionLane/resetLaneData/removeLaneData (A2) drive the data-isolation lifecycle at worktree-provision, reset, and remove time — see docs/LANES.md#data-isolation-database-redis-and-env-a2. Writes slot/ports and nothing else on the lane row: status=running means an agent is working, not that a server is listening, and conflating them would corrupt lane liveness
lib/lane-detect.js	(A3) Node.js project detection and .ccam/profile/ scaffolding. detectNode reads package.json layout (root, or backend/+frontend/) and docker-compose.yml (a service matching /postgres/i or /redis/i) — read-only, never executes anything. Any detected name written into GENERATED SHELL TEXT (an npm script name, a compose service name) must pass a strict identifier check first; a profile.env value is already safe regardless, since that file is parsed, never sourced. scaffoldProfile writes the profile, always leaving migrate/seed as an exit 0 TODO stub when a database is found rather than guessing a migration tool. checkProfile is the read-only hard gate: unresolved TODO:, a missing/non-executable hook, or a port already in use all fail it; a missing ~/.ccam/secrets.env only warns
lib/secrets.js	(A2) Reads ~/.ccam/secrets.env — machine-level database/Redis credentials, deliberately outside any repository. Parsed with lane-profile.js's literal KEY=VALUE reader, never sourced. Falls back to local defaults (with a one-time warning) when the file is absent; refuses to load a file readable by group or world rather than trusting it. Never returned by any route
lib/lane-env.js	(A2) seedEnv copies a repo's real .env into a lane on first boot (or --force) and rewrites the declared ENV_REWRITE keys (DATABASE_URL/REDIS_URL/UPLOAD_DIR) in place, byte-identical otherwise. A --force refresh preserves ENV_PRESERVE keys (e.g. JWT_SECRET) from the lane's own existing file — swapping in the source's secret would 401 a running lane until reboot. Falls back to .env.example with a warning when the source is missing. Refuses on an adopted lane: that file is the user's real config
lib/lane-services.js	(A2) ensureDatabase/dropDatabase call the profile's db-create/db-drop hooks — CCAM stays stack-agnostic on purpose. A state-dir marker file tracks whether a slot's database was already created, since a plain createdb can't be re-run safely and CCAM can't assume the hook is idempotent; this is also how upLane knows to seed only a freshly-created database. dropDatabase asserts the lane is managed and that the name being dropped is one this lane's own slot actually derives (itself or its _test sibling) before spawning anything
lib/lane-features.js	(B) Per-feature state and archive. activateFeature archives the lane's current active feature (if different) and restores the target's saved stage onto the live lanes row — the row stays the one live view every other reader already uses. canonicalizeSlug is a DELIBERATELY separate rule from worktree.js:slugify (drops a leading feat/, keeps [A-Za-z0-9._-], does not lowercase) — the two must never be conflated. clearLane (lib/lanes.js) archives the active feature (if any) before resetting; a lane that never activated one is unaffected
lib/proof.js	(C) Proof gallery: lists/serves/deletes QC screenshots grouped by feature slug (Task B's lane_features) and phase, under <lane.cwd>/.playwright-mcp/proof/<slug>/<group>/. Every path is resolved, realpath'd, and containment-checked before touching fs — the entire security surface. ensureProofLink ports Shipyard's ensure_proof_link (converge a stray clone-root proof/ onto the canonical dir); never auto-invoked, exposed only as ccam lanes proof-link
lib/named-lock.js	(D) Cross-lane named locks — the OTHER axis from lib/lane-lock.js's per-lane, in-process serialization, deliberately a separate module. mkdir is the atomicity primitive (EEXIST decides "already held" in one syscall, never check-then-create). LOCK_MAX_HOLD (default 2700s) breaks a stale holder on the next acquire, floored at 300s so the floor — not the configurable default — is the actual safety property: nothing can force-break a live holder by setting the env var low. Single-shot only; the CLI's ccam lock acquire owns the polling loop, keeping the server side non-orchestrating like every other lane primitive

API Documentation

Both JSDoc and Swagger/OpenAPI 3.0.3 are used for API documentation. JSDoc comments in route handlers provide inline documentation and type hints, while the OpenAPI spec is generated centrally and rendered three ways for interactive and read-optimized API exploration.

Layer	Source	Purpose
Inline code docs	JSDoc blocks in server/index.js, server/db.js, server/routes/*.js, and server/lib/*.js	Explain route behavior, lifecycle logic, and internal contracts close to implementation
Machine-readable API contract	server/openapi.js (createOpenApiSpec()) + fragments under server/openapi-extra/	Defines OpenAPI 3.0.3 info, schemas, parameters, and all documented /api/* paths (75 path entries, comprehensive route coverage)
Interactive docs	GET /api/openapi.json and GET /api/docs	Exposes raw OpenAPI JSON and Swagger UI (try-it-out) for exploration and integration testing
Read-optimized reference	GET /api/redoc (served by server/lib/redoc.js)	ReDoc three-panel rendering of the same spec; the ReDoc bundle is self-hosted at /api/redoc/redoc.standalone.js (never a CDN) so it works offline / air-gapped
Committed spec snapshot	openapi.yaml (repo root)	Generated from server/openapi.js via npm run openapi:yaml — mirrors the live spec, never hand-edited

The OpenAPI metadata is grounded in real project data (package.json version/license/repository/bugs), and route coverage is enforced in server/__tests__/api.test.js by asserting expected paths exist in the spec.

Request Processing

flowchart LR
    REQ[Incoming<br/>Request] --> CORS[CORS<br/>Middleware]
    CORS --> JSON[JSON Body<br/>Parser<br/>1MB limit]
    JSON --> ROUTER{Route<br/>Match}
    ROUTER -->|/api/hooks| HOOKS[hooks.js]
    ROUTER -->|/api/sessions| SESSIONS[sessions.js]
    ROUTER -->|/api/agents| AGENTS[agents.js]
    ROUTER -->|/api/events| EVENTS[events.js]
    ROUTER -->|/api/stats| STATS[stats.js]
    ROUTER -->|/api/analytics| ANALYTICS[analytics.js]
    ROUTER -->|/api/remote-sources| REMOTE[remote-sources.js]
    ROUTER -->|/api/pricing| PRICING[pricing.js]
    ROUTER -->|/api/settings| SETTINGS[settings.js]
    ROUTER -->|/api/workflows| WORKFLOWS[workflows.js]
    ROUTER -->|/api/openapi.json| OPENAPI[OpenAPI JSON]
    ROUTER -->|/api/docs| SWAGGER[Swagger UI]
    ROUTER -->|/api/health| HEALTH[Health Check]
    ROUTER -->|"* (prod)"| STATIC[Static Files<br/>client/dist]

    HOOKS --> DB[(SQLite)]
    SESSIONS --> DB
    AGENTS --> DB
    EVENTS --> DB
    STATS --> DB
    ANALYTICS --> DB
    PRICING --> DB
    SETTINGS --> DB
    WORKFLOWS --> DB

    HOOKS --> WS[WebSocket<br/>Broadcast]
    SESSIONS --> WS
    AGENTS --> WS

---

Client Architecture

Component Tree

graph TD
    APP["App.tsx<br/>Router + WebSocket"]
    LAYOUT["Layout.tsx<br/>Sidebar + Outlet"]
    SIDEBAR["Sidebar.tsx<br/>Nav (scroll-bounded with overflow<br/>chevrons) + Connection Status"]
    DASH["Dashboard.tsx"]
    KANBAN["KanbanBoard.tsx"]
    SESS["Sessions.tsx"]
    DETAIL["SessionDetail.tsx"]
    ACTIVITY["ActivityFeed.tsx"]
    SETTINGS_P["Settings.tsx"]

    ANALYTICS_P["Analytics.tsx"]
    WORKFLOWS_P["Workflows.tsx"]
    NOTFOUND["NotFound.tsx"]

    APP --> LAYOUT
    LAYOUT --> SIDEBAR
    LAYOUT --> DASH & KANBAN & SESS & DETAIL & ACTIVITY & ANALYTICS_P & WORKFLOWS_P & SETTINGS_P & NOTFOUND

    DASH --> SC1["StatCard x6<br/>(sessions/agents/subagents/<br/>events today/total events/cost)<br/>3-column grid"]
    DASH --> AC1["AgentCard[]<br/>with collapsible subagent hierarchy"]
    DASH --> EV1["Event rows"]
    DASH --> HEALTH["SystemHealthTab<br/>(health score ring, storage donut,<br/>cache/error/success gauges,<br/>tool bars, subagent effectiveness,<br/>model tokens, compaction stats)"]

    KANBAN --> COL["Agents view: 4 columns<br/>(working/waiting/<br/>completed/error)<br/>Sessions view: 5 columns<br/>(active/waiting/completed/<br/>error/abandoned)"]
    COL --> AC2["AgentCard[]"]

    SESS --> TABLE["Session Table<br/>with filters"]
    DETAIL --> OVERVIEW["SessionOverview<br/>(stat tiles, top tools,<br/>subagent breakdown,<br/>token flow, event mix)"]
    DETAIL --> AC3["AgentCard hierarchy<br/>parent → children tree"]
    DETAIL --> CONV["ConversationView<br/>(MarkdownContent + CodeBlock<br/>+ ToolCallBlock per-tool styling)"]
    DETAIL --> TL["Event Timeline"]
    ACTIVITY --> FEED["Streaming Event List<br/>(click row → expand payload;<br/>Session btn → session detail)"]
    WORKFLOWS_P --> WFC["12 D3.js components<br/>(workflows/ directory)"]

    style APP fill:#6366f1,stroke:#818cf8,color:#fff
    style LAYOUT fill:#1a1a28,stroke:#2a2a3d,color:#e4e4ed

Splash & loading UX

• SplashScreen.tsx — rendered by App.tsx as a fixed full-screen overlay alongside the router. Shows once per browser session (sessionStorage gate, read synchronously so a repeat mount never flashes). Time-aware greeting + localized tagline/subtexts (splash i18n namespace, en/zh/vi/ko) + an animated node-graph brand mark on a dark backdrop (radial glow, drifting constellation, grain). The backdrop is opaque from the first paint (no entrance fade on the root) so the app rendered behind it never flashes through; only the inner content cascades in. Holds ~2.5 s, then fades out and unmounts; click-to-skip; honors prefers-reduced-motion. CSS-only keyframes, no added dependencies.
• Loading skeletons — the shared Skeleton primitive (components/Skeleton.tsx) uses Tailwind animate-pulse. Analytics.tsx now renders a pulsing AnalyticsChartsSkeleton for the whole chart region while data is null (previously it fell back to empty/zero charts).
• workflows/CompactionImpact.tsx — redesigned from a one-bar-per-session chart into a "sessions by compaction count" histogram (D3) with axis titles, stat tiles (total / sessions affected / avg / peak), an explanatory help line, a plain-English summary, and rich React-managed hover tooltips (full-height per-bucket hit-area + bar highlight) matching the other charts.
• Workflows.tsx Section — the right-aligned section subtitle is clamped to a single line (truncate + max-w + hover title) so a long translation never wraps and unbalances the header; the full text stays in the section's i popover.

Self-hosted assets (no external CDN)

Nothing the dashboard or docs render is fetched from a third-party CDN at runtime — all fonts and scripts are served locally, so every surface works fully offline and leaks nothing to external hosts.

• React app fonts — Inter + JetBrains Mono are imported from @fontsource (latin subset) in client/src/main.tsx. Vite bundles the per-weight WOFF2 into client/dist/assets/ with content hashes at build time; there is no Google Fonts <link>. Importing the latin-* subset entry points keeps the emitted set to one WOFF2 per weight.
• Static pages (landing + wiki) — load a self-hosted @font-face sheet at the repo-root fonts/ directory (fonts/fonts.css + the *.woff2 files). The root index.html references fonts/fonts.css; the wiki references ../fonts/fonts.css (relative paths resolve under GitHub Pages).
• Wiki Mermaid — vendored as wiki/mermaid.min.js (the genuine minified mermaid@10.9.6 from npm, with a provenance banner; .prettierignored) and loaded via a local <script> instead of cdn.jsdelivr.net.
• VS Code extension — the inline getErrorHtml() error page dropped its Google Fonts loader for a system font stack (no bundler / local font path available in that webview).

Net effect: no fonts.googleapis.com, fonts.gstatic.com, or cdn.jsdelivr.net requests anywhere (verified by git grep).

PWA Architecture

The project ships three independent Progressive Web Apps. Each has its own Web App Manifest and Service Worker, so the browser treats them as separate installable applications with isolated caches.

┌─────────────────────────────────────────────────────────────────┐
│                        PWA Surface Map                          │
├──────────────────┬──────────────────┬───────────────────────────┤
│   Dashboard      │   Landing Page   │         Wiki              │
│   (client/)      │   (root)         │         (wiki/)           │
├──────────────────┼──────────────────┼───────────────────────────┤
│ manifest.json    │ manifest.json    │ manifest.json             │
│ sw.js            │ sw.js            │ sw.js                     │
│ id: dashboard    │ id: landing      │ id: wiki                  │
├──────────────────┼──────────────────┼───────────────────────────┤
│ Precache:        │ Precache:        │ Precache:                 │
│ /, manifest,     │ index.html,      │ index.html, style.css,    │
│ favicon.svg      │ favicon, og-img, │ script.js, manifest,      │
│                  │ manifest         │ favicon                   │
│ Runtime cache:   │ Runtime cache:   │ Runtime cache:            │
│ JS/CSS bundles   │ screenshot PNGs  │ (all precached)           │
│ (cache-first)    │ (cache-first)    │                           │
│                  │                  │                           │
│ Skip: /api/*,    │ N/A              │ N/A                       │
│ /ws, __vite      │                  │                           │
│                  │                  │                           │
│ + Push notifs    │                  │                           │
│ (VAPID pipeline) │                  │                           │
└──────────────────┴──────────────────┴───────────────────────────┘

Service Worker lifecycle (all three):

1. Install → skipWaiting() — new SW activates immediately, no waiting for tabs to close.
2. Activate → old caches deleted (keyed by CACHE_NAME: dashboard-v1, landing-v1, wiki-v1). Bump the version string to force a cache bust.
3. Fetch → Navigation requests are network-first with offline fallback to cached HTML. Static assets are cache-first with runtime caching on miss.

Dashboard SW specifics: The fetch handler skips /api/*, /ws, and Vite HMR (__vite) URLs so live data and development tooling are never cached. Only responses with response.type === "basic" (same-origin) are stored. The existing push notification handlers (push, notificationclick) are preserved alongside the caching logic.

Manifest icons: All three manifests reference favicon.svg with sizes="any" and type="image/svg+xml" — supported in Chrome 107+, Firefox 110+, Edge 107+. Two icon entries per manifest: one with purpose: "any" and one with purpose: "maskable".

iOS meta tags: All HTML files include <meta name="apple-mobile-web-app-capable" content="yes"> and <meta name="apple-mobile-web-app-status-bar-style" content="black-translucent"> for standalone home-screen mode on Safari.

Client Module Graph

graph TD
    MAIN["main.tsx<br/>React entry"]
    APP["App.tsx<br/>Router + WS + Notifications"]
    EB["eventBus.ts<br/>Pub/sub + connection state"]
    WS["useWebSocket.ts<br/>Auto-reconnect hook"]
    NOTIF["useNotifications.ts<br/>Browser notification triggers"]
    API["api.ts<br/>Typed fetch client"]
    TYPES["types.ts<br/>Interfaces + configs"]
    FMT["format.ts<br/>Date/time/model-name utilities"]
    DS["dataScope.ts<br/>Global data-scope store"]

    MAIN --> APP
    APP --> WS
    APP --> EB
    APP --> NOTIF
    NOTIF --> EB
    WS --> TYPES
    EB --> TYPES

    subgraph Pages
        D[Dashboard]
        K[KanbanBoard]
        S[Sessions]
        SD[SessionDetail]
        AF[ActivityFeed]
        AN[Analytics]
        WF[Workflows]
        SET[Settings]
        NF[NotFound]
    end

    APP --> D & K & S & SD & AF & AN & WF
    D & K & S & SD & AF & AN & WF --> API
    D & K & S & SD & AF & AN & WF --> EB
    D & K & S & SD & AF & AN & WF --> FMT
    SET --> API
    SET --> EB
    SET --> FMT
    D & K & S & AF & AN & WF --> DS
    DS --> API
    API --> TYPES

    subgraph Components
        L[Layout]
        SB[Sidebar]
        AGC[AgentCard]
        STC[StatCard]
        STB[StatusBadge]
        ES[EmptyState]
        TB["Tabby/<br/>(floating cat companion)"]
    end

    D --> STC & AGC & STB
    K --> AGC
    S --> STB & ES
    SD --> AGC & STB
    AF --> STB & ES
    APP --> L
    L --> SB
    L --> TB
    EB --> TB

    style TYPES fill:#3178C6,stroke:#5a9fd4,color:#fff
    style EB fill:#f59e0b,stroke:#fbbf24,color:#000
    style API fill:#10b981,stroke:#34d399,color:#fff

Routing

graph LR
    ROOT["/ (index)"] --> DASH[Dashboard]
    KANBAN_R["/kanban"] --> KANBAN[KanbanBoard]
    SESS_R["/sessions"] --> SESS[Sessions]
    DETAIL_R["/sessions/:id"] --> DETAIL[SessionDetail]
    ACT_R["/activity"] --> ACT[ActivityFeed]
    AN_R["/analytics"] --> AN[Analytics]
    WF_R["/workflows"] --> WF[Workflows]
    CC_R["/cc-config"] --> CC[CcConfig]
    LANES_R["/lanes"] -->|redirect| RUN_R["/run"]
    RUN_R --> WORKSPACE["Workspace<br/>lanes + runs merged"]
    SET_R["/settings"] --> SET[Settings]
    NF_R["/*"] --> NF[NotFound]

    ALL["All routes"] --> LAYOUT["Layout wrapper<br/>(Sidebar + Outlet)"]

Route	Page	Data Sources
/	Dashboard	Two tabs (Monitor / Health). Monitor: GET /api/stats, GET /api/agents, GET /api/events, GET /api/agents?session_id={sid} (subagent hierarchy), dynamic item counts via ResizeObserver. Health: GET /api/settings/info + GET /api/workflows (5 s auto-refresh) — composite health score, storage donut, cache/error/success gauges, tool invocation bars, subagent effectiveness, model token distribution, compaction stats
/kanban	KanbanBoard	View toggle persisted in localStorage. Agents view: GET /api/agents?status={each} per-status (default 10000 cap). Sessions view: GET /api/sessions?status={each}&limit=10000 per-status. Each column then paginates client-side at COLUMN_PAGE_SIZE=10; the WS subscription scopes to the active view.
/sessions	Sessions	GET /api/sessions?status=&q=&limit=PAGE_SIZE&offset=page*PAGE_SIZE — true server-side pagination. The search box passes q to the server (300 ms debounced). Response carries total for the paginator UI. Cost computation runs server-side over the visible page only. Polls /api/run (and listens for run_status) to badge any row whose session is currently being driven from /run with a clickable green ▶ Run pill
/sessions/:id	SessionDetail	GET /api/sessions/:id (agents + events), GET /api/sessions/:id/stats (overview tiles, top tools, subagent breakdown, token totals — debounced live-refresh on new_event/agent_*/session_updated), GET /api/sessions/:id/transcripts (Conversation tab transcript list), GET /api/sessions/:id/transcript (cursor-paginated message stream, including inline session_event rename markers; optional run_id resolves a workflow inner agent's nested transcript). Probes /api/run (and listens for run_status) to surface a green "Open in Run page" banner when this session is currently being driven by an in-flight Run handle. When the session sits in the Waiting overlay, renders a yellow waiting-for-input banner naming the awaiting_reason (Needs input / Turn done / At prompt / Interrupted) and how long it has waited; every Waiting StatusBadge across the app carries the same reason as a hover tooltip, with an inline nested chip on the wider surfaces (Sessions table, session-detail header) — compact card badges (Kanban/Dashboard) stay tooltip-only
/activity	ActivityFeed	GET /api/events?limit=100 — click row to expand inline payload; "Session →" button navigates to /sessions/:id
/analytics	Analytics	GET /api/analytics
/workflows	Workflows	GET /api/workflows?status=active|completed, GET /api/workflows/session/:id + WebSocket auto-refresh (3s debounce)
/cc-config	CcConfig	12-tab Claude Code configuration explorer. Reads via GET /api/cc-config/{overview,skills,agents,commands,output-styles,plugins,marketplaces,mcp,hooks,hook-scripts,keybindings,statusline,settings,memory}. Mutations for skills/agents/commands/output-styles/memory — including the per-project file-based auto-memory store (*.md under ~/.claude/projects/<slug>/memory/, grouped by project and searchable in the Memory tab, with clickable MEMORY.md index links that scroll to + highlight the matching fact file) — via PUT /api/cc-config/file + DELETE /api/cc-config/file (timestamped backups, atomic writes). The Keybindings tab additionally offers a structured inline editor that persists via PUT /api/cc-config/keybindings (same backup-first, atomic-write guarantees). GET /api/cc-config/file?path=… for single-file viewer. GET /api/cc-config/backups for the recovery modal. Subscribes to cc_config_changed WS messages for live refresh on both dashboard mutations and external file edits picked up by cc-watcher. The Settings tab leads with a client-side Current configuration summary that resolves the /config options (model, verbose, theme, output style, effort, auto-compact, notifications, …) across user / project / project-local scopes, showing defaults when unset. Live / Offline indicator next to the title
/run	Workspace	Merged workspace page combining lanes and runs. Spawns claude subprocesses with chat-style streaming UI, tied to lanes: the UI opens on a cwd, calls POST /api/lanes/ensure when no lane owns it yet, then starts runs through POST /api/lanes/:id/start (which accepts mode: "conversation" | "headless" and effort: "low" | "medium" | "high"). A finished run releases its lane (clears run_id, returns status to idle). Displays a horizontal lane strip at the top, the selected lane's pipeline map, and run configuration/console/history below. GET /api/run/{binary,cwds,files} for pre-flight + @-file autocomplete; POST /api/run/:id/message for follow-up turns; DELETE /api/run/:id to stop (lane-tied runs go through POST /api/lanes/:id/stop instead). GET /api/run/history?laneId=<n> lists only that lane's runs. WS messages: run_stream (includes stream_event deltas), run_status, run_input_ack, lane_update. Streaming pipeline: each WS envelope is dispatched through flushSync so React 18 doesn't batch bursts into a single render; a useTypewriterEnvelopes hook drips text/thinking deltas via requestAnimationFrame so even short replies type in; the merge code preserves _streaming and the delta-accumulated content array when claude's canonical assistant envelope arrives mid-stream so thinking blocks aren't dropped. Tier 1 TUI parity: collapsible-to-pill limitations banner, slash + @-file autocomplete (dropdowns open upward, slash matching uses tiered scoring), live token / context-window meter, status header. The console never writes a lane's stage — stage moves only through ccam stage commands. Live / Offline indicator next to the title
/settings	Settings	GET /api/settings/info, GET /api/pricing, GET /api/pricing/cost + localStorage for notification prefs. Hosts the Remote Data Sources panel (components/RemoteSources.tsx) — CRUD + test + sync over /api/remote-sources, live status from remote_source.status WS messages
/*	NotFound	None (static 404 page)

Activity Feed Interaction Model

The Activity Feed (/activity) separates two previously conflated interactions into distinct affordances:

flowchart LR
    ROW["Event row\n(div role=button)"] -->|click / Enter / Space| EXPAND["Toggle inline\nEventDetail panel"]
    ROW --> BTN["Session → button\n(right edge, Link)"]
    BTN -->|click - stopPropagation| NAV["/sessions/:id"]
    EXPAND --> DETAIL["EventDetail.tsx\nparsed payload fields\n+ terminal JSON blocks"]

    style ROW fill:#1a1a28,stroke:#2a2a3d,color:#e4e4ed
    style BTN fill:#6366f1,stroke:#818cf8,color:#fff
    style DETAIL fill:#10b981,stroke:#34d399,color:#fff
    style NAV fill:#f59e0b,stroke:#fbbf24,color:#000

• Row click (anywhere except the Session button) toggles the EventDetail dropdown for the selected event. Chevron rotates 90° as a visual indicator.
• Session → button uses e.stopPropagation() to navigate to session details without triggering the expand toggle.
• Expanded state is tracked in a Set<number> (expandedEvents) allowing multiple rows to be open simultaneously.
• Keyboard accessible: Enter and Space on the row trigger expand; the Session button is a standard <a> element navigable by Tab.

Workflows Page Architecture

The Workflows page (/workflows) is the most visualization-heavy page, composed of 12 child components in client/src/components/workflows/. Most D3.js rendering is done client-side using data from two API endpoints. The aggregate endpoint accepts an optional ?status=active|completed query parameter to filter all workflow data by session status.

graph TD
    WF["Workflows.tsx<br/>Page orchestrator"]:::root
    API_AGG["GET /api/workflows?status=...<br/>Aggregate data (filterable)"]
    API_DI["GET /api/workflows/session/:id<br/>Session drill-in"]
    WS_D["WebSocket auto-refresh<br/>(3s debounce)"]

    WF --> API_AGG
    WF --> API_DI
    WS_D --> WF

    WF --> S1["WorkflowStats<br/>Summary cards"]
    WF --> S2["OrchestrationDAG<br/>Horizontal DAG —<br/>Sessions → Main → Subagents → Outcomes"]
    WF --> S3["ToolExecutionFlow<br/>d3-sankey tool transitions"]
    WF --> S4["AgentCollaborationNetwork<br/>Force-directed pipeline graph"]
    WF --> S5["SubagentEffectiveness<br/>SVG success rings +<br/>day-of-week sparklines"]
    WF --> S6["WorkflowPatterns<br/>Auto-detected sequences"]
    WF --> S7["ModelDelegationFlow<br/>Model → agent routing"]
    WF --> S8["ErrorPropagationMap<br/>React horizontal bars +<br/>API/session error support"]
    WF --> S9["ConcurrencyTimeline<br/>Swim-lane parallel execution"]
    WF --> S10["SessionComplexityScatter<br/>D3 bubble chart"]
    WF --> S11["CompactionImpact<br/>Token compression analysis"]
    WF --> S12["SessionDrillIn<br/>Searchable session explorer<br/>(3 tabs: tree / timeline / events)"]

    classDef root fill:#6366f1,stroke:#818cf8,color:#fff

Component	Visualization	D3 Feature
OrchestrationDAG	Horizontal DAG of aggregate spawning patterns	Custom DAG layout, capped at top 7 subagent types with overflow node
ToolExecutionFlow	Tool-to-tool transition Sankey diagram	d3-sankey
AgentCollaborationNetwork	Agent pipeline graph with directed edges	d3-force with arrowheads and frequency labels
SubagentEffectiveness	Scorecard grid with success rate rings	SVG arc rendering, day-of-week sparklines (Mon-Sun). Per-bar tooltip is rendered through createPortal to document.body and positioned with viewport-clamped fixed coordinates so it escapes the card's overflow:hidden (and any hover:translate containing block) and is never clipped by the card edge — fixes Sun/Sat/Mon/Fri visibility
WorkflowPatterns	Common orchestration sequences	Pattern detection from event data; clicking a row expands an inline detail panel with the full step chain, a stats grid, a deterministic narrative (shape buckets: solo / two-step / short / long; loop detection; frequency bucket: dominant > 50% / common > 25% / regular > 10% / niche), and a practical suggestion bucket. All copy is i18n-driven (workflows.patterns.detail.*)
ModelDelegationFlow	Model routing through agent hierarchies	Hierarchical layout
ErrorPropagationMap	Error clustering by hierarchy depth with API/session event errors	Pure React horizontal bars (replaced D3 bar chart), eventErrors support for API and session-level errors
ConcurrencyTimeline	Swim-lane parallel agent execution	Time-scaled horizontal bars
SessionComplexityScatter	Duration vs agents vs tokens	D3 bubble/scatter chart
CompactionImpact	Token compression events and recovery	Before/after comparison
SessionDrillIn	Per-session agent tree, tool timeline, events	Searchable dropdown with pagination, 3 tabs

Cross-filtering: Clicking nodes in the OrchestrationDAG filters data in other sections. JSON export: All workflow data can be exported as JSON from the page header.

Tooltip rendering strategy

Every chart in the Workflows page follows a single, deterministic tooltip pattern designed to avoid the failure modes of naive React tooltips (laggy mousemove re-renders, sticky tooltips after D3 re-renders, clipping by parent overflow:hidden):

• One DOM-ref tooltip element per chart. Each chart owns a single <div ref={tipRef}> that lives at the bottom of its render tree. D3 mouse handlers mutate that element's content imperatively (textContent, appendChild, inline style), so hovering never triggers a React re-render of the SVG.
• No mousemove follow. The tooltip is positioned once on mouseenter from the hovered element's getBoundingClientRect(), with viewport clamping (8 px margin) and an automatic flip below → above when there's no room. Position never updates as the cursor moves, which removes per-pixel state churn.
• Container-level mouseleave fallback. The chart's outer wrapper also calls hideTip() on leave. If a node-level handler is missed because D3 destroyed the element under the cursor on data refresh, the wrapper guarantees dismissal.
• Re-render safety. Each chart's render effect ends with hideTip() so any stale tooltip from before a websocket-driven refresh is cleared the moment new data arrives.
• Fade transitions. Tooltips stay in the DOM with opacity: 0 and pointer-events: none, transitioning over 120 ms — show/hide feels smooth instead of flickering, and the element never intercepts pointer events that would prevent mouseleave from firing on the chart.
• Portal escape for clipped containers. SubagentEffectiveness cards use overflow:hidden plus a hover translate (which becomes the fixed-position containing block), so its sparkline tooltip is rendered with react-dom.createPortal(…, document.body) rather than as a child of the card. Coordinates are computed from the bar's bounding rect and clamped to the viewport, so the tooltip is visible on every day of the week regardless of the card's screen position.

Structured info popovers

Two classes of explanatory popover sit on top of the chart layer, both i18n-driven:

• Stat-card popovers (WorkflowStats.tsx). Each of the six headline cards (Avg Agent Depth, Avg Subagents/Session, Agent Success Rate, Most Common Flow, Avg Compactions, Avg Duration) carries an info i icon at the bottom-right of the card. Hovering it opens a fixed-positioned, viewport-clamped popover with three sections: a value+label header, a "How it's calculated" paragraph (workflows.stats.tooltip.calc.*), and a "What this number means" paragraph that renders "{value} {phrase} means {interpretation}". The interpretation comes from a deterministic, value-bucket function (interp*) — pure rule-based mapping with no AI generation, so the same input always yields the same explanation across all three locales.
• Chart-section popovers (Workflows.tsx → ChartInfoPopover). The i icon next to each section title (1–11) opens a structured "What this shows / How to read it / Why it matters" popover sourced from workflows.chartInfo.<sectionKey>.*. Each of the 11 charts has its own three-paragraph entry, fully translated to en/vi/zh.

Both popover classes use the same fixed-position + viewport-clamp algorithm: anchor right of the icon (or center for chart-section popovers), clamp to a viewport margin, and flip above when there isn't enough room below. They are never clipped by the sidebar, the right edge of the screen, or any ancestor's overflow:hidden.

---

Internationalization Architecture

The client localization stack is powered by i18next + react-i18next (client/src/i18n/index.ts) and currently supports four languages: English (en), Chinese (zh), Vietnamese (vi), and Korean (ko). Language detection prefers localStorage (i18nextLng) and falls back to the browser locale (navigator) with en as final fallback.

flowchart LR
    A["Browser load"] --> B["LanguageDetector<br/>localStorage -> navigator"]
    B --> C["Resolved language<br/>en | zh | vi | ko (fallback en)"]
    C --> D["Namespace resources<br/>common/nav/dashboard/sessions/..."]
    D --> E["React pages/components<br/>useTranslation(ns)"]
    E --> F["format.ts locale mapping<br/>en-US | zh-CN | vi-VN | ko-KR"]
    F --> G["Localized labels,<br/>dates, number formatting,<br/>and model name display"]

See docs/I18N.md for resource strategy, key naming conventions, localization tests, troubleshooting, and rollout checklists.

Coverage scope. The translation layer extends end-to-end through the Workflows tooltip surfaces — workflows.stats.tooltip.* (calculation copy, deterministic value-bucket interpretations, metric phrases), workflows.chartInfo.* (per-chart "What / How to read / Why" entries for all 11 sections), workflows.{orchestration,toolFlow,pipeline,modelDelegation,concurrency}.tooltip.* (per-graph hover content), and workflows.patterns.detail.* (Workflow Patterns expansion narrative + suggestion buckets) — plus the Settings additions: settings.pricing.tooltip.* (pricing rule lookup, % wildcard syntax, manual-update reminder), settings.claudeHome.* (CLAUDE_HOME panel labels), and the full settings.import.* block (now translated to vi/zh, where the panel previously fell back to English).

---

Database Design

Entity Relationship Diagram

erDiagram
    sessions ||--o{ agents : has
    sessions ||--o{ events : has
    sessions ||--o{ token_usage : tracks
    agents ||--o{ events : generates
    agents ||--o{ agents : spawns

    sessions {
        TEXT id PK "UUID"
        TEXT name "Human-readable label"
        TEXT status "active|completed|error|abandoned"
        TEXT cwd "Working directory"
        TEXT model "Claude model ID"
        TEXT started_at "ISO 8601"
        TEXT ended_at "ISO 8601 or NULL"
        TEXT metadata "JSON blob"
        TEXT awaiting_input_since "ISO 8601 or NULL — set by waiting Notifications"
        TEXT awaiting_reason "notification|stop|session_start|interrupted or NULL"
        TEXT source "Data source — 'local' or a remote source id; NOT NULL DEFAULT 'local'"
    }

    agents {
        TEXT id PK "UUID or session_id-main"
        TEXT session_id FK "References sessions.id"
        TEXT name "Main Agent — {session name} or subagent description"
        TEXT type "main|subagent"
        TEXT subagent_type "Explore|general-purpose|etc"
        TEXT status "working|waiting|completed|error"
        TEXT task "Current task description"
        TEXT current_tool "Active tool name or NULL"
        TEXT started_at "ISO 8601"
        TEXT ended_at "ISO 8601 or NULL"
        TEXT parent_agent_id FK "References agents.id"
        TEXT metadata "JSON blob"
        TEXT awaiting_input_since "ISO 8601 or NULL — main-agent waiting flag"
        TEXT awaiting_reason "notification|stop|session_start|interrupted or NULL"
    }

    events {
        INTEGER id PK "Auto-increment"
        TEXT session_id FK "References sessions.id"
        TEXT agent_id FK "References agents.id"
        TEXT event_type "PreToolUse|PostToolUse|Stop|etc"
        TEXT tool_name "Tool that triggered the event"
        TEXT summary "Human-readable summary"
        TEXT data "Full event JSON"
        TEXT created_at "ISO 8601"
    }

    token_usage {
        TEXT session_id PK "FK to sessions + part of composite PK"
        TEXT model PK "Model identifier + part of composite PK"
        TEXT speed PK "standard or fast (fast mode) — pricing dimension"
        TEXT inference_geo PK "global or us (data residency) — pricing dimension"
        TEXT service_tier PK "standard or batch (Batch API) — pricing dimension"
        INTEGER input_tokens "Current JSONL total"
        INTEGER output_tokens "Current JSONL total"
        INTEGER cache_read_tokens "Current JSONL total"
        INTEGER cache_write_tokens "Total ephemeral cache writes (5m + 1h)"
        INTEGER cache_write_1h_tokens "Subset stored at the 1h tier; 5m = total - 1h"
        INTEGER web_search_requests "server_tool_use web search count"
        INTEGER web_fetch_requests "server_tool_use web fetch count"
        INTEGER code_execution_requests "server_tool_use code execution count"
        INTEGER baseline_input "High-water baseline; effective = live + baseline = max ever seen (one per metric)"
    }

    model_pricing {
        TEXT model_pattern PK "SQL LIKE pattern e.g. claude-opus-4-6%"
        TEXT display_name "Human-readable name"
        REAL input_per_mtok "Cost per million input tokens"
        REAL output_per_mtok "Cost per million output tokens"
        REAL cache_read_per_mtok "Cost per million cache read tokens (cache hits)"
        REAL cache_write_per_mtok "Cost per million 5m cache-write tokens"
        REAL cache_write_1h_per_mtok "Cost per million 1h cache-write tokens"
        REAL fast_input_per_mtok "Fast-mode input rate (0 = none)"
        REAL fast_output_per_mtok "Fast-mode output rate (0 = none)"
        REAL intro_input_per_mtok "Intro input rate, used when usage date <= intro_until (0 = none)"
        REAL intro_output_per_mtok "Intro output rate"
        REAL intro_cache_read_per_mtok "Intro cache-read rate"
        REAL intro_cache_write_per_mtok "Intro 5m cache-write rate"
        REAL intro_cache_write_1h_per_mtok "Intro 1h cache-write rate"
        TEXT intro_until "Promo cutoff YYYY-MM-DD; usage on/before uses intro rates, after uses standard (NULL = no intro)"
        TEXT updated_at "ISO 8601"
    }

    push_subscriptions {
        TEXT endpoint PK "Subscription URL"
        TEXT p256dh "Public key"
        TEXT auth "Auth secret"
        TEXT created_at "ISO 8601"
    }

    remote_sources {
        TEXT id PK "Source id — also stamped onto sessions.source"
        TEXT label "Human-readable name"
        TEXT host "SSH host"
        INTEGER ssh_port "SSH port"
        TEXT identity_file "Optional SSH identity file path or NULL (no secrets stored)"
        TEXT remote_home "Remote home holding ~/.claude/projects, or NULL"
        INTEGER enabled "1|0 — polled by the background sync when 1"
        TEXT status "idle|syncing|ok|error"
        TEXT last_error "Last sync error or NULL"
        TEXT last_sync_at "ISO 8601 or NULL"
        TEXT last_sync_counts "JSON import counters from the last sync or NULL"
        TEXT created_at "ISO 8601"
        TEXT updated_at "ISO 8601"
    }

    alert_rules ||--o{ alert_events : fires

    alert_rules {
        TEXT id PK "UUID"
        TEXT name "User-facing rule name"
        TEXT rule_type "event_pattern|inactivity|status_duration|token_threshold"
        TEXT config "Type-specific JSON config"
        INTEGER enabled "1|0"
        INTEGER cooldown_seconds "Per-scope dedup window, default 300"
        TEXT created_at "ISO 8601"
        TEXT updated_at "ISO 8601"
    }

    alert_events {
        INTEGER id PK "Auto-increment"
        TEXT rule_id FK "References alert_rules.id, ON DELETE CASCADE"
        TEXT rule_name "Snapshot — survives rule edits"
        TEXT rule_type "Snapshot"
        TEXT session_id "No FK — alert history survives session cleanup"
        TEXT agent_id "Affected agent or NULL"
        TEXT message "Human-readable alert text"
        TEXT details "JSON context blob"
        TEXT triggered_at "ISO 8601"
        TEXT acknowledged_at "ISO 8601 or NULL"
    }

    webhook_targets ||--o{ webhook_deliveries : delivers

    webhook_targets {
        TEXT id PK "UUID"
        TEXT name "User-facing target name"
        TEXT type "provider key — slack|discord|teams|telegram|pagerduty|… (15)"
        TEXT url "Endpoint URL (may be '' when derived) — server-only, masked in responses"
        INTEGER enabled "1|0"
        TEXT secret "Generic-family HMAC-SHA256 signing secret or NULL"
        TEXT headers "Generic-family extra request headers (JSON) or NULL"
        TEXT rule_ids "JSON array scoping to rules, or NULL = all"
        TEXT config "Provider params JSON (routing_key, chat_id, …); secrets redacted in responses"
        TEXT created_at "ISO 8601"
        TEXT updated_at "ISO 8601"
    }

    webhook_deliveries {
        INTEGER id PK "Auto-increment"
        TEXT target_id FK "References webhook_targets.id, ON DELETE CASCADE"
        TEXT target_name "Snapshot"
        TEXT target_type "Snapshot"
        INTEGER alert_id "alert_events.id, NULL for test pings (no FK)"
        TEXT status "success|failed"
        INTEGER status_code "Last HTTP status or NULL"
        INTEGER attempts "Attempt-chain length"
        TEXT error "Failure reason or NULL"
        TEXT created_at "ISO 8601"
    }

Indexes

Index	Table	Column(s)	Purpose
idx_agents_session	agents	session_id	Fast agent lookup by session
idx_agents_status	agents	status	Kanban board column queries
idx_events_session	events	session_id	Session detail event list
idx_events_type	events	event_type	Filter events by type
idx_events_created	events	created_at DESC	Activity feed ordering
idx_events_session_type	events	session_id, event_type	Per-session event-type filters
idx_events_agent_type	events	agent_id, event_type	Keeps importSubagentFromJsonl's per-tool-event data LIKE dedup an index seek instead of a full events scan — a large re-import (startup sweep touching a subagent-heavy session) drops from tens of seconds to sub-second
idx_sessions_status	sessions	status	Status filter on Sessions page and Kanban Sessions view
idx_sessions_started	sessions	started_at DESC	Default sort order
idx_sessions_source	sessions	source	Data-scope (?sources=) filtering by source
idx_alert_events_triggered	alert_events	triggered_at DESC	Alert feed ordering
idx_alert_events_rule	alert_events	rule_id	Cooldown lookup per rule
idx_alert_events_session	alert_events	session_id	Per-session alert history
idx_webhook_deliveries_target	webhook_deliveries	target_id, created_at DESC	Per-target delivery log + last-delivery lookup
idx_webhook_deliveries_created	webhook_deliveries	created_at DESC	Delivery-log pruning (newest 2000)

SQLite Configuration

Pragma	Value	Rationale
journal_mode	WAL	Concurrent reads during writes, better performance for read-heavy workload
foreign_keys	ON	Referential integrity enforcement
busy_timeout	5000	Wait up to 5s for write lock instead of failing immediately

Prepared Statements

All queries use prepared statements (db.prepare()) for:

• Security -- parameterized queries prevent SQL injection
• Performance -- compiled once, executed many times
• Reliability -- syntax errors caught at startup, not runtime

Notable prepared statements include findStaleSessions (used by SessionStart to identify active sessions with no activity for a configurable number of minutes), touchSession (bumps updated_at on every event), and reactivateSession / reactivateAgent (used when a previously completed/abandoned session receives new work or stop events — Stop/SubagentStop reactivate completed/abandoned sessions to handle sessions imported before the server started).

---

WebSocket Protocol

Connection

• Path: /ws
• Protocol: Standard WebSocket (RFC 6455)
• Heartbeat: Server sends ping every 30 seconds; clients that don't pong are terminated

Message Format

All messages are JSON with this envelope:

{
  type: "session_created" | "session_updated" | "agent_created" | "agent_updated" | "new_event"
      | "alert_triggered" | "alert_updated" | "workflow_upserted" | "remote_source.status";
  data: Session | Agent | DashboardEvent | AlertEvent | WorkflowRun | RemoteSourceStatus;
  timestamp: string; // ISO 8601
}

The remote_source.status message (emitted by the Remote Data Sources sync poller and the /api/remote-sources routes) carries { id, status, error?, last_sync_at? }, where status is one of idle | syncing | ok | error | deleted.

Message Flow

graph TD
    subgraph "Server Events"
        A[Hook event processed]
        B[Session created/updated via API]
        C[Agent created/updated via API]
    end

    subgraph "Broadcast"
        BC["broadcast(type, data)<br/>Serializes to JSON,<br/>sends to all OPEN clients"]
    end

    subgraph "Client Handling"
        WS["useWebSocket hook<br/>Auto-reconnect on close"]
        EB["eventBus.publish(msg)"]
        SUB1["Dashboard subscriber"]
        SUB2["Kanban subscriber"]
        SUB3["Sessions subscriber"]
        SUB4["SessionDetail subscriber"]
        SUB5["ActivityFeed subscriber"]
        SUB6["Workflows subscriber<br/>(3s debounce)"]
    end

    A & B & C --> BC
    BC --> WS
    WS --> EB
    EB --> SUB1 & SUB2 & SUB3 & SUB4 & SUB5 & SUB6
    EB --> SUB7["Tabby companion subscriber"]

    style BC fill:#10b981,stroke:#34d399,color:#fff
    style EB fill:#f59e0b,stroke:#fbbf24,color:#000

The Tabby companion (see Tabby Companion Subsystem) is an additional read-only eventBus subscriber. It consumes the existing message envelope above and introduces no new WebSocket message types and no protocol changes.

Client Reconnection

The useWebSocket hook implements automatic reconnection:

stateDiagram-v2
    [*] --> Connecting: Component mounts
    Connecting --> Connected: onopen
    Connected --> Closed: onclose
    Connected --> Closed: onerror → close
    Closed --> Connecting: setTimeout(2000ms)
    Connected --> [*]: Component unmounts
    Closed --> [*]: Component unmounts

---

Hook Integration

Hook Handler Design

scripts/hook-handler.js is designed to be a minimal, fail-safe forwarder that POSTs each hook to one ingest target per unique SQLite data directory (different databases still each get hooks; same database never double-ingests):

flowchart TD
    START[Claude Code fires hook] --> STDIN[Read stdin to EOF]
    STDIN --> RESOLVE["resolveAllDashboardPorts()<br/>via server/lib/server-info.js"]
    RESOLVE --> PARSE{Parse JSON?}
    PARSE -->|Success| POST["POST to 127.0.0.1:{port}/api/hooks/event<br/>(one per unique dataDir, parallel)"]
    PARSE -->|Failure| WRAP["Wrap raw input as<br/>#123;raw: ...#125;"]
    WRAP --> POST
    POST --> AGG{Promise.all settled}
    AGG -->|All resolved or rejected| EXIT0[exit = 0]
    AGG -->|Any single timeout 3s| DESTROY[Destroy that request only]
    DESTROY --> AGG

    SAFETY[Safety net: setTimeout 5s] --> EXIT0_SAFETY[exit = 0]

    style EXIT0 fill:#10b981,stroke:#34d399,color:#fff
    style EXIT0_SAFETY fill:#10b981,stroke:#34d399,color:#fff

Key design decisions:

• Always exits 0 — never blocks Claude Code regardless of any server's state.
• 3-second HTTP timeout per target + 5-second process-wide safety net.
• Uses Node.js http module directly — no dependencies.
• Resolution order is env override → discovery file → default:
  • CLAUDE_DASHBOARD_PORT forces a single target (no fan-out, no discovery).
  • Otherwise server/lib/server-info.js reads ~/.claude/.agent-dashboard.json, prunes dead-PID entries, and returns one live port per unique dataDir (lowest port wins when Docker and npm run dev share ~/.claude/agent-dashboard). The handler POSTs to each returned port in parallel.
  • If neither yields anything, the handler falls back to 4820.
• Per-target promises never reject — a dead listener can't starve the others, and the handler can wait on Promise.all for clean exit timing.

Hook Installation

scripts/install-hooks.js modifies ~/.claude/settings.json:

flowchart TD
    START[Run install-hooks.js] --> READ{~/.claude/settings.json<br/>exists?}
    READ -->|Yes| PARSE[Parse JSON]
    READ -->|No| EMPTY[Start with empty object]
    PARSE --> CHECK
    EMPTY --> CHECK

    CHECK[Ensure hooks section exists]
    CHECK --> LOOP["For each hook type:<br/>SessionStart, PreToolUse, PostToolUse,<br/>Stop, SubagentStop, Notification, SessionEnd"]

    LOOP --> EXISTS{Our hook<br/>already installed?}
    EXISTS -->|Yes| UPDATE[Update command path]
    EXISTS -->|No| APPEND[Append to array]
    UPDATE --> NEXT
    APPEND --> NEXT

    NEXT{More hook types?}
    NEXT -->|Yes| LOOP
    NEXT -->|No| WRITE[Write settings.json]
    WRITE --> DONE[Print summary]

Preserves existing hooks -- only adds or updates entries containing hook-handler.js.

Plugin installs declare the same hooks instead

When the dashboard is installed as the ccam Claude Code plugin, the eight hook entries are declared inline in .claude-plugin/plugin.json (each running ${CLAUDE_PLUGIN_ROOT}/scripts/hook-handler.js), and install-hooks.js is not used at all. claude plugin install itself materializes these into ~/.claude/settings.json with ${CLAUDE_PLUGIN_ROOT} already resolved to the plugin's cache path — confirmed by installing the plugin for real and inspecting the file, not just reading the docs. Both a checkout install and a plugin install writing hooks at once would POST every event twice — events carry no id, so ingest cannot deduplicate them, and every token and cost figure would double. Two guards keep that from happening silently:

• scripts/plugin-bootstrap.js strips checkout-style hook-handler.js entries out of ~/.claude/settings.json on session start (backing the file up as settings.json.ccam-bak first) and logs what it removed. Because the plugin's own entries ALSO contain hook-handler.js (just resolved to a cache path instead of a raw filesystem one), a plain substring match cannot tell them apart — isCheckoutHookEntry() only treats an entry as removable when its command does NOT resolve under ~/.claude/plugins/cache/, so the plugin's own legitimate hooks are never touched.
• install-hooks.js warns when the plugin runtime state exists, and /ccam-doctor reports any surviving checkout-style duplicates as a FAIL using the same isCheckoutHookEntry() predicate.

scripts/plugin-bootstrap.js also owns the rest of the plugin's runtime: the Node >= 22.5 gate (node:sqlite), an atomic mkdir lock, the dependency install into ~/.claude/agent-dashboard/runtime/, the ~/.local/bin/ccam launcher, and the detached server spawn with NODE_PATH and DASHBOARD_CLIENT_DIST pointed at that runtime directory. It never writes into the plugin cache, which Claude Code garbage-collects and replaces on every update. Full behavior: docs/PLUGINS.md.

---

Import Pipeline

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 and cost values are identical to those captured in real time.

Design goals

• Accuracy by construction — any code path that creates a session goes through a single importSession entry point. There is no "import math" distinct from "live math."
• Idempotence — re-importing the same source must never double-count. Session IDs are the dedup key; compaction baseline_* columns preserve pre-compaction token totals so re-ingesting a compacted transcript never shrinks historical cost.
• Source flexibility — users bring history from the default location, any folder, or a drag-dropped archive. A single generalized walker feeds the parser regardless of the source.
• Safety — archive extraction enforces path containment and an extraction size cap (zip/tar/gzip-bomb defense), and every request has its own staging directory reclaimed on both success and error paths.

Component overview

flowchart TD
    subgraph Clients
      UI["Browser: Settings →<br/>Import History panel"]
      CLI["CLI: npm run import-history"]
      STARTUP["Server startup<br/>(auto-import)"]
    end

    UI -->|POST /api/import/guide<br/>POST /api/import/rescan<br/>POST /api/import/scan-path<br/>POST /api/import/upload| RT["server/routes/import.js"]
    CLI --> IMP["scripts/import-history.js<br/>importAllSessions()"]
    STARTUP --> IMP

    RT -->|archives| AR["server/lib/archive.js<br/>extractZip / extractTar /<br/>extractGzSingle"]
    RT -->|directory walk| FD["importFromDirectory()"]
    AR -.->|temp workDir| FD
    IMP --> FD

    FD -->|per-session| PS["parseSessionFile()"]
    FD -->|per-subagent| PSA["parseSubagentFile()"]
    PS --> IS["importSession()"]
    PSA --> IS

    IS -->|prepared stmts<br/>single transaction| DB[("SQLite:<br/>sessions / agents / events /<br/>token_usage")]
    IS -.->|progress throttled<br/>~150ms| WS["server/websocket.js<br/>broadcast('import.progress')"]
    WS -.-> UI

    style UI fill:#a855f7,stroke:#c084fc,color:#fff
    style RT fill:#1a1a28,stroke:#2a2a3d,color:#e4e4ed
    style AR fill:#1a1a28,stroke:#2a2a3d,color:#e4e4ed
    style FD fill:#1a1a28,stroke:#2a2a3d,color:#e4e4ed
    style IMP fill:#1a1a28,stroke:#2a2a3d,color:#e4e4ed
    style IS fill:#f59e0b,stroke:#fbbf24,color:#000
    style DB fill:#10b981,stroke:#34d399,color:#fff

Continuous background sync. The startup auto-import (autoImportLegacySessions) is a one-time backfill, marker-gated by .legacy-import.done — so a project folder that appears after first launch, and whose sessions never flow through hooks (e.g. a checkout run with host-only hooks disabled), would otherwise stay invisible until a manual rescan. To close that gap, startSessionSync (server/index.js) keeps ~/.claude/projects in sync through three triggers that share one mtimeCache and a single coalesced sweep, the exported syncDefaultProjects(dbModule, { mtimeCache }):

1. Immediate — one sweep at startup, so a project the marker-gated backfill missed surfaces right away rather than after the first interval.
2. Watcher — a debounced fs.watch on the projects tree fires a sweep the instant a new session file or project folder appears (near-real-time, no poll wait). Events for files already in mtimeCache — active transcripts being appended to — are ignored, so a busy session never thrashes the importer. Recursive watching is used only on macOS/Windows (native, stable); on Linux, where Node's userland recursive watcher trips on the high-churn projects tree (same hazard lib/cc-watcher.js avoids), the root plus each immediate child folder are watched non-recursively instead.
3. Poll — a periodic safety-net sweep (watchers can miss events / not fire on network filesystems), tunable via DASHBOARD_SESSION_SYNC_MS (default 30 s); 0 disables the poll but leaves the watcher running.

Each sweep re-parses only files whose mtime is new or has advanced (the common "nothing changed" tick is just a handful of stat calls), funnels them through the same parseSessionFile + importSession pipeline as every other path, and broadcasts session_created for newly imported sessions / session_updated for grown ones — the same events hooks emit, so the UI refreshes live. All timers and watchers are unref'd and best-effort; nothing here blocks shutdown or can take down the server.

Upload request sequence

The upload path is the most complex of the three — it must accept multipart data, extract archives safely, stage them on disk, then invoke the shared importer. The sequence below captures the complete request/response path including the failure modes explicitly guarded against.

sequenceDiagram
    autonumber
    participant UI as Settings UI
    participant API as /api/import/upload
    participant M as multer (disk)
    participant AR as archive.js
    participant IMP as importFromDirectory
    participant DB as SQLite
    participant WS as WebSocket /ws

    UI->>API: POST multipart files[]
    API->>M: route through uploadMiddleware
    M->>M: mkTempDir('ccam-upload-*')<br/>stored on req._ccamUploadDir
    M->>M: fileFilter: reject unsupported<br/>(tracked in req._ccamRejected)
    alt All files rejected
      API-->>UI: 400 NO_FILES<br/>+ rejected_files[]
    else Files accepted
      API->>AR: mkTempDir('ccam-import-work-*')
      loop per uploaded file
        API->>AR: extractInto(srcPath, workDir, name)
        AR->>AR: safeJoin: reject absolute / ..
        AR->>AR: enforce MAX_EXTRACT_BYTES
        alt Extraction cap exceeded
          AR-->>API: throw ExtractionLimitError
          API-->>UI: 413 EXTRACTION_LIMIT_EXCEEDED
          API-->>WS: import.progress{phase:error}
          Note over API: break and cleanup
        else OK
          AR-->>API: {extracted, skipped}
        end
        API->>WS: import.progress{phase:extract}
      end
      API->>IMP: importFromDirectory(dbModule, workDir)
      IMP->>IMP: collectJsonlFiles (recursive)
      IMP->>IMP: parseSessionFile per JSONL
      IMP->>IMP: findSessionSubagents (2 layouts)
      IMP->>DB: importSession in one transaction
      IMP-->>WS: import.progress{phase:parse,complete}
      API-->>UI: 200 {imported, backfilled,<br/>skipped, errors, rejected_files}
    end
    API->>AR: rmTempDir(workDir)
    API->>M: rmTempDir(req._ccamUploadDir)

Idempotence and cost accuracy

flowchart LR
    A[Parse session JSONL] --> B{Session ID<br/>already in DB?}
    B -->|no| C[Insert session,<br/>main agent, events,<br/>token_usage]
    B -->|yes| D{Any new fields,<br/>tools, compactions,<br/>turn durations?}
    D -->|no| E[skipped = true]
    D -->|yes| F[Backfill: insert<br/>missing events +<br/>enrich metadata]
    F --> G[backfilled = true]

    C --> H[replaceTokenUsage]
    F --> H
    H --> I[baseline := max of old + new<br/>effective = max of old_effective, new_live]
    I --> K[Overwrite live with new totals]

    style I fill:#10b981,stroke:#34d399,color:#fff
    style E fill:#1a1a28,stroke:#2a2a3d,color:#e4e4ed
    style G fill:#f59e0b,stroke:#fbbf24,color:#000

The baseline_* columns keep the effective total (live + baseline) a monotonic high-water mark: the cost endpoint sums input_tokens + baseline_input (and the matching output, cache_read, cache_write pairs), and replaceTokenUsage sets baseline := max(old_live + old_baseline − new_live, 0) so effective = max(old_effective, new_live). This never decreases (a compaction that shrinks the transcript keeps its pre-compaction usage) and — crucially — never inflates past the largest value ever seen. The earlier formula added the current value into baseline on any decrease, which two writers of different scope (the live hook writer stores main-only tokens; importSession stores main+subagents) could ratchet upward on every downward fluctuation — one 26-day session accumulated a baseline ~11× its real usage before this was fixed.

Supported source layouts

Layout	Example	Handling
Default Claude Code	<proj>/<sid>.jsonl	Session transcript
Default subagent	<proj>/<sid>/subagents/agent-*.jsonl	Paired with parent on discovery
Alternative subagent	<proj>/subagents/<sid>/agent-*.jsonl	Paired with parent on discovery
Workflow inner-agent (nested)	<proj>/<sid>/subagents/workflows/<runId>/agent-*.jsonl	Summarized by Workflow-run ingest; transcript resolved on read + preserved in the durable snapshot
Orphan subagent (no parent JSONL in source)	<proj>/subagents/<sid>/agent-*.jsonl	importFromDirectory probes both candidates; attaches if sid exists
Flat JSONL drop	<root>/<sid>.jsonl	Recognized as a loose session
Archives (.zip, .tar, .tar.gz, .tgz)	any of the above nested inside	Extracted into a per-request temp dir, then walked by the same importer
Single-file gzip	any.jsonl.gz	Gunzipped in streaming mode with size cap

Safety model

Threat	Mitigation
Path traversal via archive entries	archive.safeJoin resolves under the extraction root; any .. or absolute path returns null
Zip / tar / gzip bombs	MAX_EXTRACT_BYTES (default 4 GB) enforced by running byte counter; aborts with ExtractionLimitError
Per-file upload size abuse	multer limits.fileSize = MAX_UPLOAD_BYTES (default 1 GB)
Too many files per request	multer limits.files = MAX_UPLOAD_FILES (default 2000)
Unsupported file types	fileFilter drops them early and reports them in rejected_files[]
Concurrent upload temp-dir collisions	Per-request temp dir on req._ccamUploadDir; created in multer destination, cleaned in finally
Arbitrary absolute path on scan-path	Validated: must be absolute (after ~ expansion), exist, and be a directory
Relative / traversal paths on scan-path	Rejected with INVALID_INPUT

Environment variables

Variable	Default	Purpose
CCAM_IMPORT_MAX_BYTES	1 GB	Maximum size per uploaded file
CCAM_IMPORT_MAX_FILES	2000	Maximum files per upload request
CCAM_IMPORT_MAX_EXTRACT_BYTES	4 GB	Ceiling on total uncompressed bytes from any single archive

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.

---

Workflow-Tool Run Ingestion

"Dynamic workflows" — the fleets of sub-agents spawned by the Claude Code Workflow tool (and self-paced /loop runs) — are invisible to hooks. Inner agent() calls emit no PreToolUse/SubagentStop events, so hook-based ingestion can never see the fleet. Instead, everything is persisted on disk under the launching session's transcript folder:

<projects>/<enc-cwd>/<sessionId>/
  workflows/
    scripts/<name>-wf_<runId>.js          # the workflow script — written at LAUNCH
    wf_<runId>.json                       # the run journal — written at COMPLETION
  subagents/
    workflows/<runId>/agent-<agentId>.jsonl  # inner-agent transcript (current builds — NESTED per run)
    agent-<agentId>.jsonl                    # flat layout — older builds / regular sub-agents

The run journal (wf_<runId>.json) is the first-class record: identity (runId, taskId, workflowName), lifecycle (status, startTime, durationMs, defaultModel), aggregates (agentCount, totalTokens, totalToolCalls), phases[], and workflowProgress[] — one entry per inner agent with agentId, agentType, model, state, label, phaseTitle, tokens, tool calls, duration, and previews. Critically, workflowProgress[].agentId is the exact agent-<agentId>.jsonl basename, so the workflow → inner-agent linkage is explicit. Current Claude Code builds write that transcript nested under subagents/workflows/<runId>/; older builds (and all regular sub-agents) write it flat under subagents/. Both layouts are resolved on read — see "Reading full agent text in the UI" below.

The terminal-journal constraint

wf_<runId>.json is written only when the workflow finishes. While a run is in flight, its live state lives in a per-run dir subagents/workflows/<runId>/: a streaming journal.jsonl (a started / result event per inner agent) and the growing agent-<id>.jsonl transcripts. The ingester handles both phases:

• Completed runs are ingested in full from the terminal journal: a workflows row (keyed by run_id) plus linked inner-agent rows, with phases and per-agent labels.
• Running runs (no terminal journal yet) are ingested live by ingestLiveWorkflow: it reads journal.jsonl for each agent's started/done state + result, and parses the live agent-<id>.jsonl transcripts (via parseSubagentFile) for real-time per-agent tokens, tool calls, duration, and model. It synthesizes a progress[] so the UI shows live activity (phase/label aren't known until the terminal journal lands). The run is status: running and replaced by the terminal journal on completion (idempotent upsert by run_id; launch time preserved). A launch script with no run dir yet falls back to a minimal running row.

Ingestion module and triggers

server/lib/workflow-ingest.js (ingestWorkflowsForSession) reuses the import pipeline's parseSubagentFile and importSubagentFromJsonl, so inner agents become agent rows under the same ${sessionId}-jsonl-<agentId> id scheme the subagent importer already uses — ingestion therefore converges with any prior subagent import (no duplicate rows). Each inner agent is stamped with agents.workflow_run_id + agents.workflow_phase. The per-agent table in the UI is read from the journal's progress[] JSON.

Cost folding. Inner agents are sidechain contexts whose token usage is NOT in the parent transcript (the same reason combineSessionTokens adds subagent tokens). So the fleet's real token split — parsed from each agent-<id>.jsonl — is written into the session's token_usage under a namespaced service_tier = 'workflow' bucket. That bucket is isolated from the main-transcript writer's rows (which use the real tier), so the two never collide or clobber, while calculateCost still sums them per model. The write is a full recompute each ingest → replaceTokenUsage's replace semantics make it idempotent (no double-count across re-ingests).

Ingestion runs from five fail-safe, off-the-response-path triggers:

1. Live — routes/hooks.js, on Stop / SubagentStop / SessionEnd (the lifecycle hooks that bracket a workflow finishing).
2. Real-time poll — startWorkflowPoll (server/index.js) scans active sessions every ~12 s, skipping any whose workflow artifacts are unchanged. The newest-mtime fingerprint (workflowsMaxMtime) includes the live journal.jsonl + agent-*.jsonl of any in-flight run (bounded to runs without a terminal journal), so the poll re-ingests as a running workflow's tokens/tools/agents grow — the UI updates live without waiting for a hook or completion. Tunable via DASHBOARD_WORKFLOW_POLL_MS (0 disables).
3. Periodic — the server/index.js maintenance sweep, scanning active sessions' workflows/ directories (flips running → completed when a journal lands without a subsequent hook).
4. Backfill — a one-time pass in autoImportLegacySessions ingests historical on-disk workflows for every recorded session.
5. Offline CLI import — the batch importer (importAllSessions / importFromDirectory in scripts/import-history.js, backing ccam import rescan / ccam import path and the /api/import/* routes) calls ingestWorkflowsForSession per imported session, after the batch's transcripts land and outside the SQLite transaction (the ingest is async). Triggers 1–3 all run inside the server; this is the only path that links a fleet whose journal never reached a live server — a headless claude -p run, a CI job, or an HPC/cluster compute node emits no hooks — so an offline rescan links the inner agents instead of leaving them orphaned (workflow_run_id = NULL, run stuck at 1 agent). Idempotent: converges on the same ${sessionId}-jsonl-<agentId> rows, cheap for sessions with no workflow artifacts (early return).

Each ingest that changes anything broadcasts workflow_upserted and a session_updated (so the cost views refetch) over WebSocket. Runs surface via GET /api/workflows/runs (list) and GET /api/workflows/runs/:runId (detail with linked agents + events), and are attached to the launching session via the workflows[] field on GET /api/sessions/:id. The UI shows them in a "Workflow Runs" panel on the Workflows page and a subsection on Session Detail.

Reading full agent text in the UI

The run journal only carries truncated promptPreview / resultPreview strings (Claude Code truncates them with a trailing …), so the panel alone can never show an inner agent's complete prompt or result. The full text lives in the per-agent agent-<agentId>.jsonl transcript, which the dashboard surfaces on demand:

• Dual-layout resolution. server/lib/claude-home.js exposes resolveAgentTranscriptInDir(subagentsDir, agentId, runId?), used by all three sub-agent path resolvers (getSubagentTranscriptPath, findSubagentTranscriptPath, getSnapshotSubagentTranscriptPath). It checks the flat path first (so regular sub-agents resolve exactly as before), then the nested workflows/<runId>/ path. When runId is known the run dir is read directly; when it is unknown the nested tree is scanned and a match is returned only if exactly one run contains that agentId — an ambiguous id across runs resolves to null rather than guessing.
• run_id query param. GET /api/sessions/:id/transcript accepts an optional run_id=wf_<…> alongside agent_id, threaded into the resolver chain so a workflow inner agent's nested transcript is found deterministically. The endpoint shape is unchanged; the param is additive.
• Lazy fetch on expand. The Workflow Runs panel (client/src/components/workflows/WorkflowRunsPanel.tsx) fetches the transcript the first time a result row is expanded (deduped per ${run_id}::${agentId}), derives prompt + result via extractPromptResult, and renders the full text — falling back to the journal teaser while loading, on error, or for schema-mode agents whose final turn is a tool call rather than text. Nothing is eagerly ingested into the DB. "Full text" means the complete message body up to the endpoint's per-message 10,240-char cap (limit ≤ 200 messages).
• Durable snapshot. The snapshot writer (snapshotTranscript in scripts/import-history.js) preserves nested workflow transcripts via the dedicated findSessionWorkflowSubagents discovery — mirroring the live subagents/workflows/<runId>/ subpath into the snapshot dir — so the full text still resolves after Claude Code prunes the live files under its cleanupPeriodDays retention. This is kept separate from findSessionSubagents (flat sub-agents) so the regular sub-agent import path is unchanged and nested inner-agents are never double-counted.

Schema

A workflows table (run_id PK, session_id FK ON DELETE CASCADE, status as an open string, phases/progress as JSON blobs, source = journal | live) plus two additive agents columns (workflow_run_id, workflow_phase). No existing table, response shape, or WebSocket message type changes.

---

Agent Extension Layer

The repository includes a triple extension strategy:

• Claude Code-native extensions (CLAUDE.md, .claude/rules, .claude/skills)
• Codex-native extensions (AGENTS.md, .codex/rules, .codex/agents, .codex/skills)
• Plugin marketplace (plugins/, .claude-plugin/marketplace.json) — 10 plugins with 53 skills, 14 agents, 30 slash commands, 3 CLI tools
• Codex-native extensions (AGENTS.md, .codex/rules, .codex/agents, .codex/skills)

graph TD
    USER["Developer"] --> CLAUDE["Claude Code"]
    USER --> CODEX["Codex"]

    CLAUDE --> C_MEM["CLAUDE.md"]
    CLAUDE --> C_RULES[".claude/rules/*"]
    CLAUDE --> C_SKILLS[".claude/skills/*"]
    CLAUDE --> C_PLUGINS["plugins/<br/>10 plugins, 53 skills"]

    CODEX --> X_MEM["AGENTS.md"]
    CODEX --> X_RULES[".codex/rules/*.rules"]
    CODEX --> X_AGENTS[".codex/agents/*.toml"]
    CODEX --> X_SKILLS[".codex/skills/*"]

    style C_PLUGINS fill:#8b5cf6,stroke:#a78bfa,color:#fff

Claude Code extension scope

• CLAUDE.md defines always-on project working agreements.
• .claude/rules/ adds path-scoped guidance by file area.
• .claude/skills/ provides reusable workflows:
  • onboarding
  • feature shipping
  • MCP operations
  • live issue debugging
• .claude/agents/ provides specialized review workers:
  • backend reviewer
  • frontend reviewer
  • MCP reviewer
• plugins/ provides distributable plugin marketplace (see Plugin Marketplace):
  • ccam-analytics (session reports, cost analysis, usage trends, productivity scoring)
  • ccam-productivity (standups, weekly reports, sprint summaries, workflow optimization)
  • ccam-devtools (session debugging, hook diagnostics, data export, health checks)
  • ccam-insights (pattern detection, anomaly alerting, optimization, session comparison)
  • ccam-dashboard (status checks, quick stats, MCP integration)
  • ccam-cost-guard (budget guardrails, week/month-end spend forecasting, cost-threshold alerts, model-routing savings)
  • ccam-sessions (session forensics: search, timeline, transcript replay, per-cwd rollup, cleanup)
  • ccam-workflows (multi-agent orchestration & fleet intelligence: DAG map, delegation audit, concurrency, error propagation, fleet runs)
  • ccam-quality (reliability & SLOs: error scan, API-error report, hook-failure audit, SLO check, regression alert)
  • ccam-config (Claude Code config & memory governance: config audit, memory review, skill/MCP/hook inventory)

Codex extension scope

• AGENTS.md provides project-wide default behavior.
• .codex/rules/default.rules controls external execution decisions.
• .codex/agents/ provides custom subagent templates.
• .codex/skills/ provides reusable task workflows.

---

Plugin Marketplace

The repository includes an official Claude Code plugin marketplace with ten production-ready plugins. These extend Claude Code itself (not just the dashboard) with skills, agents, slash commands, hooks, CLI tools, and MCP integration — all deeply grounded in the actual dashboard data model. The five original plugins (ccam-analytics, ccam-productivity, ccam-devtools, ccam-insights, ccam-dashboard) were each deepened with more agents/skills and a commands/ dir of slash commands, and five new plugins were added: ccam-cost-guard (budget guardrails — set budgets, forecast week/month-end spend, cost-threshold alerts, model-routing savings, with a fail-safe Stop hook), ccam-sessions (session forensics — search, timeline, transcript replay, per-cwd rollup, cleanup), ccam-workflows (multi-agent orchestration & fleet intelligence — DAG map, delegation audit, concurrency, error propagation, fleet runs, built on the 11-dataset workflow intelligence API), ccam-quality (reliability & SLOs — error scan, API-error report, hook-failure audit, SLO check, regression alert), and ccam-config (Claude Code config & memory governance — config audit, memory review, skill/MCP/hook inventory via the Config Explorer API).

Marketplace Architecture

graph TD
    subgraph Marketplace[".claude-plugin/marketplace.json"]
        M["Marketplace Manifest"]
    end

    subgraph Plugins["plugins/"]
        A["ccam-analytics<br/>4 skills, 1 agent, 1 CLI"]
        P["ccam-productivity<br/>4 skills, 1 agent"]
        D["ccam-devtools<br/>4 skills, 1 agent, 2 CLIs"]
        I["ccam-insights<br/>4 skills, 1 agent"]
        C["ccam-dashboard<br/>2 skills, MCP config"]
        G["ccam-cost-guard<br/>5 skills, 1 agent, Stop hook"]
        S["ccam-sessions<br/>5 skills, 1 agent"]
        W["ccam-workflows<br/>5 skills, 1 agent"]
        Q["ccam-quality<br/>5 skills, 1 agent"]
        F["ccam-config<br/>5 skills, 1 agent"]
    end

    subgraph API["Dashboard API (port 4820)"]
        STATS["/api/stats"]
        ANALYTICS["/api/analytics"]
        PRICING["/api/pricing/cost"]
        WORKFLOWS["/api/workflows/session/:id"]
        SESSIONS["/api/sessions"]
    end

    M --> A & P & D & I & C & G & S & W & Q & F
    A & P & I --> ANALYTICS & PRICING & WORKFLOWS
    D --> STATS & SESSIONS
    C --> STATS & ANALYTICS
    G --> PRICING & ANALYTICS
    S --> SESSIONS
    W --> WORKFLOWS
    Q --> STATS & SESSIONS
    F --> STATS

    style M fill:#6366f1,stroke:#818cf8,color:#fff
    style A fill:#10b981,stroke:#34d399,color:#fff
    style P fill:#f59e0b,stroke:#fbbf24,color:#000
    style D fill:#ef4444,stroke:#f87171,color:#fff
    style I fill:#8b5cf6,stroke:#a78bfa,color:#fff
    style C fill:#06b6d4,stroke:#22d3ee,color:#000
    style G fill:#ec4899,stroke:#f472b6,color:#fff
    style S fill:#14b8a6,stroke:#2dd4bf,color:#000
    style W fill:#a855f7,stroke:#c084fc,color:#fff
    style Q fill:#f43f5e,stroke:#fb7185,color:#fff
    style F fill:#3b82f6,stroke:#60a5fa,color:#fff

Plugin Structure

Each plugin follows the official Claude Code plugin specification:

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

Skills are namespaced: /ccam-analytics:session-report, /ccam-productivity:daily-standup, etc.

Plugin Catalog

Plugin	Skills	Agent	CLI Tools	Hooks
ccam-analytics	session-report, cost-breakdown, usage-trends, productivity-score	analytics-advisor	ccam-stats	Stop, SubagentStop
ccam-cost-guard	budget-set, spend-forecast, cost-alert, model-savings, daily-budget-check	budget-sentinel	—	Stop
ccam-productivity	daily-standup, weekly-report, sprint-summary, workflow-optimizer	productivity-coach	—	SessionStart, SessionEnd
ccam-devtools	session-debug, hook-diagnostics, data-export, health-check	issue-triager	ccam-doctor, ccam-export	—
ccam-insights	pattern-detect, anomaly-alert, optimization-suggest, session-compare	insights-advisor	—	—
ccam-sessions	session-search, session-timeline, transcript-replay, cwd-rollup, session-cleanup	session-investigator	—	—
ccam-workflows	dag-map, delegation-audit, concurrency-report, error-propagation, fleet-runs	orchestration-analyst	—	—
ccam-quality	error-scan, api-error-report, hook-failure-audit, slo-check, regression-alert	reliability-engineer	—	—
ccam-config	config-audit, memory-review, skill-inventory, mcp-audit, hook-inventory	config-auditor	—	—
ccam-dashboard	dashboard-status, quick-stats	—	—	—

Totals: 10 plugins, 53 skills, 14 agents, 30 slash commands, 3 CLI tools, 3 hook configurations, 1 MCP config. Each plugin is installable via claude plugin install <name>@smartgift-claude-code-monitor, and a server test (server/__tests__/plugins-marketplace.test.js) validates the marketplace↔directory bijection plus every plugin.json, agent, skill, and command.

Data Model Grounding

Every skill and agent references the actual dashboard API response shapes:

Data Source	Key Fields Used by Plugins
Token tracking	input_tokens, output_tokens, cache_read_input_tokens, cache_creation_input_tokens + 4 baseline_* columns (preserve pre-compaction data)
Cost engine	(tokens / 1M) × rate_per_mtok for each type; longest model_pattern match wins; pre-seeded Opus/Sonnet/Haiku rates
Session metadata	thinking_blocks, turn_count, total_turn_duration_ms, usage_extras ({ service_tiers[], speeds[], inference_geos[] })
Event types	PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, Notification, Compaction, APIError, TurnDuration, ToolError, Interrupted
Workflow intelligence	11 datasets per session: stats, orchestration (DAG), toolFlow (transitions), effectiveness, patterns, modelDelegation, errorPropagation (by depth), concurrency (lanes), complexity (score), compaction (impact), cooccurrence (agent pairs)
Agent hierarchy	Recursive CTE with parent_agent_id, subagent_type, depth tracking

Key Derived Metrics

Plugins compute these from raw API data:

• Cache efficiency: cache_read / (cache_read + input) — trending up = improving prompt reuse
• Compaction pressure: sum(baseline_*) / sum(effective_tokens) — high = frequent context overflow
• Tool success rate: PostToolUse count / PreToolUse count — should be ~1.0; gap = tool failures
• Turn velocity: turn_count / (total_turn_duration_ms / 1000) — turns per second
• Cost per completed session: total_cost / completed_sessions

Installation

# Marketplace install
claude plugin marketplace add Smartgift-AI/Claude-Code-Monitor
claude plugin install ccam-analytics@smartgift-claude-code-monitor

# Local development testing
claude --plugin-dir plugins/ccam-analytics

Full documentation: docs/plugins.md

---

MCP Integration

The repository includes an enterprise-grade local MCP server in mcp/ that exposes dashboard functionality as tools for MCP hosts such as Claude Code and Claude Desktop. It supports three transport modes: stdio (for MCP host child-process integration), HTTP+SSE (for remote/networked clients), and an interactive REPL (for operator debugging).

MCP Transport Selection

flowchart TD
    START["MCP Server Start"] --> ARG{"CLI arg or env?"}
    ARG -->|"--transport=stdio\nor default"| STDIO["stdio transport\nJSON-RPC over stdin/stdout"]
    ARG -->|"--transport=http\nor --http"| HTTP["HTTP + SSE transport\nExpress on :8819"]
    ARG -->|"--transport=repl\nor --repl"| REPL["Interactive REPL\nreadline with tab completion"]

    STDIO --> HOST["MCP Host\n(Claude Code / Desktop)"]
    HTTP --> ENDPOINTS["Endpoints:\n/mcp (Streamable HTTP)\n/sse (Legacy SSE)\n/messages (Legacy POST)\n/health (status)"]
    REPL --> CLI["Operator Terminal\ncolored output, JSON highlighting\ntool invocation, domain browsing"]

    style STDIO fill:#6366f1,stroke:#818cf8,color:#fff
    style HTTP fill:#f59e0b,stroke:#fbbf24,color:#000
    style REPL fill:#a855f7,stroke:#c084fc,color:#fff

MCP Runtime Topology

graph LR
    HOST["MCP Host<br/>(Claude Code / Claude Desktop)"]
    HTTP_CLIENT["Remote MCP Client"]
    OPERATOR["Operator CLI"]

    MCP_STDIO["MCP Server<br/>stdio"]
    MCP_HTTP["MCP Server<br/>HTTP+SSE :8819"]
    MCP_REPL["MCP Server<br/>REPL"]

    API["Dashboard API<br/>http://127.0.0.1:4820/api/*"]
    DB["SQLite"]

    HOST -->|"stdin/stdout"| MCP_STDIO
    HTTP_CLIENT -->|"POST /mcp · GET /sse"| MCP_HTTP
    OPERATOR -->|"interactive CLI"| MCP_REPL

    MCP_STDIO -->|"validated HTTP"| API
    MCP_HTTP -->|"validated HTTP"| API
    MCP_REPL -->|"validated HTTP"| API
    API --> DB

    style HOST fill:#6366f1,stroke:#818cf8,color:#fff
    style HTTP_CLIENT fill:#f59e0b,stroke:#fbbf24,color:#000
    style OPERATOR fill:#a855f7,stroke:#c084fc,color:#fff
    style MCP_STDIO fill:#0f766e,stroke:#14b8a6,color:#fff
    style MCP_HTTP fill:#0f766e,stroke:#14b8a6,color:#fff
    style MCP_REPL fill:#0f766e,stroke:#14b8a6,color:#fff
    style API fill:#339933,stroke:#5cb85c,color:#fff
    style DB fill:#003B57,stroke:#005f8a,color:#fff

MCP Module Architecture

graph TD
    ENTRY["src/index.ts<br/>(transport router)"]
    SERVER["src/server.ts"]
    CONFIG["config/app-config.ts"]
    CLIENT["clients/dashboard-api-client.ts"]
    CORE["core/*<br/>logger, tool-registry, tool-result"]
    POLICY["policy/tool-guards.ts"]
    TOOLS["tools/index.ts"]
    DOMAINS["tools/domains/*<br/>observability, sessions, agents,<br/>events, pricing, maintenance"]

    T_HTTP["transports/http-server.ts<br/>Express SSE + Streamable HTTP"]
    T_REPL["transports/repl.ts<br/>readline + tab completion"]
    T_COLL["transports/tool-collector.ts<br/>handler collection for REPL"]
    UI["ui/*<br/>banner, colors, formatter"]

    ENTRY --> CONFIG
    ENTRY --> SERVER
    ENTRY --> T_HTTP
    ENTRY --> T_REPL
    ENTRY --> T_COLL
    SERVER --> TOOLS
    TOOLS --> DOMAINS
    DOMAINS --> CLIENT
    DOMAINS --> POLICY
    DOMAINS --> CORE
    T_HTTP --> UI
    T_REPL --> UI

MCP Safety Model

• API target is restricted to loopback hosts only (127.0.0.1, localhost, ::1)
• Tool inputs are schema-validated with zod before execution
• Mutating tools require MCP_DASHBOARD_ALLOW_MUTATIONS=true
• Destructive tools additionally require MCP_DASHBOARD_ALLOW_DESTRUCTIVE=true and explicit confirmation token
• Logging is written to stderr only so stdio protocol traffic is never corrupted

MCP Tool Domains

• Observability: health/stats/analytics/system/export/snapshot
• Sessions: list/get/create/update
• Agents: list/get/create/update
• Events: list + hook event ingestion
• Pricing: rule CRUD + total/per-session cost
• Maintenance: cleanup/reimport/reinstall-hooks/clear-data (guarded)

---

State Management

Client-Side Architecture

The client uses a deliberately simple state management approach:

graph TD
    subgraph "Data Sources"
        REST["REST API<br/>(initial load + refresh)"]
        WSM["WebSocket Messages<br/>(real-time updates)"]
        LS["localStorage<br/>(notification prefs)"]
    end

    subgraph "Distribution"
        EB["eventBus<br/>(Set-based pub/sub)"]
    end

    subgraph "App-Level Hooks"
        NOTIF_H["useNotifications<br/>reads prefs, fires<br/>browser notifications"]
        TABBY_H["useTabbyBrain<br/>derives cat mood +<br/>speech from WS stream"]
    end

    subgraph "Page State"
        US1["useState<br/>Dashboard"]
        US2["useState<br/>KanbanBoard"]
        US3["useState<br/>Sessions"]
        US4["useState<br/>SessionDetail"]
        US5["useState<br/>ActivityFeed"]
        US6["useState<br/>Analytics"]
        US8["useState<br/>Workflows"]
        US7["useState<br/>Settings"]
    end

    REST --> US1 & US2 & US3 & US4 & US5 & US6 & US8 & US7
    WSM --> EB
    EB --> US1 & US2 & US3 & US4 & US5 & US6 & US8 & US7
    EB --> NOTIF_H
    EB --> TABBY_H
    LS --> NOTIF_H
    LS --> TABBY_H
    LS --> US7

Why no Redux / Zustand / Context:

• Each page owns its data and lifecycle
• No cross-page state sharing needed (notification prefs use localStorage as the shared store; the one small global store is lib/dataScope.ts, which holds the app-wide data scope — the set of sources whose data is shown — and appends ?sources= to the data queries)
• WebSocket events trigger reload or append, not complex state merging
• Simpler mental model, fewer abstraction layers, easier to debug

Event Bus

The eventBus is a Set-based pub/sub with subscribe() returning an unsubscribe function. It also tracks WebSocket connection state, exposing connected (boolean getter), setConnected(value), and onConnection(handler) so any component can subscribe to connection status changes.

// Subscribe to messages in useEffect, unsubscribe on cleanup
useEffect(() => {
  return eventBus.subscribe((msg) => {
    if (msg.type === "agent_updated") load();
  });
}, [load]);

// Read connection state reactively (e.g. with useSyncExternalStore)
const wsConnected = useSyncExternalStore(eventBus.onConnection, () => eventBus.connected);

This pattern ensures:

• No memory leaks (cleanup on unmount)
• No stale closures (subscribe with latest callback ref)
• Only active pages receive messages
• Connection state is available to any component without prop drilling

---

Browser Notification System

The dashboard implements a robust notification system using the Web Push API (VAPID) and Service Workers, allowing for reliable delivery even when the browser is backgrounded or closed.

Notification Architecture

graph TD
    subgraph "Server Side"
        API_P["Push API<br/>(/api/push/*)"]
        WP["web-push lib<br/>(VAPID)"]
        DB_P["push_subscriptions<br/>table"]
        KEYS["vapid-keys.json<br/>(persisted)"]
    end

    subgraph "Client Side"
        SW["Service Worker<br/>(sw.js)"]
        PUSH["useNotifications hook<br/>(subscribes via SW)"]
        PREFS["localStorage<br/>(event preferences)"]
        BROWSER["Browser Push Service<br/>(FCM/Mozilla/Safari)"]
    end

    API_P --> WP
    WP -->|signed push| BROWSER
    BROWSER --> SW
    SW -->|showNotification| USER["Developer"]
    PUSH -->|subscribe| SW
    PUSH -->|POST /subscribe| API_P
    API_P --> DB_P
    WP -->|read keys| KEYS

    style SW fill:#f59e0b,stroke:#fbbf24,color:#000
    style BROWSER fill:#10b981,stroke:#34d399,color:#fff

Key Components

Component	Responsibility
VAPID Pipeline	Uses the web-push library on the server. VAPID keys are auto-generated on first run and persisted to data/vapid-keys.json to ensure subscription continuity.
Service Worker	Located at client/public/sw.js. It runs independently of the dashboard tab, listening for push events from the browser's push service. It handles notificationclick to focus/open the dashboard.
macOS Audio Support	Notifications are explicitly sent with silent: false and sound: "default". This overrides macOS behavior that would otherwise suppress audio for web notifications.
Subscription Management	The dashboard registers the service worker and requests a PushSubscription. This subscription (endpoint and keys) is stored in the push_subscriptions table, indexed by endpoint.
Event Routing	When a WebSocket event (e.g., session_created) is broadcast, the server also triggers sendPushToAll(), which iterates through active subscriptions and sends signed VAPID payloads.

Notification Flow

flowchart TD
    EVENT["Server Event<br/>(e.g. SessionStart)"] --> PREFS{"User Prefs<br/>Enabled?"}
    PREFS -->|No| SKIP[Skip]
    PREFS -->|Yes| SUBS["Fetch all subscriptions<br/>from DB"]
    SUBS --> LOOP["For each subscription:"]
    LOOP --> SEND["webpush.sendNotification()"]
    SEND --> BROWSER["Browser Push Service"]
    BROWSER --> SW["Service Worker"]
    SW --> SHOW["showNotification(title, body)<br/>silent: false"]

    style SHOW fill:#10b981,stroke:#34d399,color:#fff

Preference Storage

Notification preferences remain in localStorage (agent-monitor-notifications) for UI-side filtering, while the actual push delivery is managed by the server-side subscription store.

Preference	UI Key	Logic
Master Toggle	enabled	Controls whether the subscription is active
New Session	onNewSession	Filtered during push fan-out
Session Error	onSessionError	Filtered during push fan-out
Session Complete	onSessionComplete	Filtered during push fan-out
Subagent Spawn	onSubagentSpawn	Filtered during push fan-out

Service Worker Caching

The dashboard's Service Worker (client/public/sw.js) serves dual purposes: push notification delivery (described above) and runtime caching. The fetch handler is split by URL shape so a rebuild can never leave a user stuck on a stale UI:

• Cache-first for /assets/* — Vite emits content-hashed filenames, so a given URL is immutable for the lifetime of that build. Cached aggressively for fast warm starts; old entries simply never get re-requested when a new build ships different hashes.
• Network-first with cache fallback for everything else (navigations, the SW itself, manifest.json, icons, root /). The user always gets the freshest UI while online; the cache is only consulted when the network fails.
• Bypass for /api/*, /ws, and Vite HMR (__vite) — these are never cached.

Cache versioning is controlled by the CACHE_NAME constant (dashboard-v2). On activate, any caches whose key doesn't match are deleted, so bumping the version string forces a clean refresh. skipWaiting() + clients.claim() ensure the new SW takes over immediately.

client/src/main.tsx snapshots navigator.serviceWorker.controller before registration and listens for controllerchange: when a new SW activates on an already-controlled page, it reloads exactly once so the page picks up the new asset URLs without a hard refresh. The first install (no previous controller) does not reload.

These behaviors are reinforced by explicit Cache-Control headers from the production Express static middleware in server/index.js: immutable, max-age=31536000 for /assets/*; no-cache, must-revalidate for index.html, sw.js, and manifest.json; a short revalidation window for other static files. The SPA fallback sendFile sends the same no-cache header. The native desktop shell (macOS and Windows) loads the dashboard from this same in-process server (NODE_ENV=production), so it inherits the policy automatically.

---

Update Notifier Subsystem

The Update Notifier is a detection-only subsystem that tells the user when the dashboard's git checkout is behind its tracked upstream branch. It never mutates the checkout or restarts the server — those actions are intentionally left to the user in a terminal, because a process cannot reliably replace itself without an external supervisor.

Module Layout

graph TD
    subgraph Server
        LIB["update-check.js<br/>getUpdatesStatus"]
        SCHED["update-scheduler.js<br/>startUpdateScheduler"]
        ROUTE["routes/updates.js<br/>GET status, POST check"]
        WS["websocket.js<br/>broadcast update_status"]
    end

    subgraph Client
        API["lib/api.ts<br/>api.updates"]
        BUS["lib/eventBus.ts<br/>subscribe and publish"]
        MODAL["UpdateNotifier.tsx<br/>dismissedSha in localStorage"]
        SIDEBAR["Sidebar.tsx<br/>Check-for-updates button"]
    end

    SCHED -->|tick every 5 min| LIB
    ROUTE -->|on request| LIB
    SCHED -->|fingerprint changed| WS
    ROUTE -->|on POST check| WS
    WS -->|update_status frame| API
    API -->|mirror to bus| BUS
    WS --> BUS
    BUS --> MODAL
    BUS --> SIDEBAR
    SIDEBAR -->|click| API
    MODAL -->|click| API

    style WS fill:#6366f1,stroke:#818cf8,color:#fff
    style LIB fill:#10b981,stroke:#34d399,color:#fff

Detection Pipeline

sequenceDiagram
    autonumber
    participant Sched as Scheduler
    participant Lib as update-check lib
    participant Git as git
    participant WS as WebSocket broadcast
    participant Client as Modal and Sidebar

    Sched->>Lib: tick
    Lib->>Lib: check .git exists
    alt not a git repo
        Lib-->>Sched: soft payload, git_repo false
    else git repo
        Lib->>Git: git remote, pick upstream then origin
        alt no remotes configured
            Lib-->>Sched: soft payload, no remotes message
        else
            Lib->>Git: git fetch canonical remote, 120s timeout
            alt fetch fails
                Lib-->>Sched: soft payload with fetch_error
            else
                Lib->>Git: rev-parse HEAD and canonical ref
                Lib->>Git: rev-list --count HEAD..ref
                Lib->>Git: read current branch and its tracked upstream
                Lib-->>Sched: full payload with situation and manual_command
            end
        end
    end
    Sched->>Sched: compute fingerprint
    alt fingerprint changed
        Sched->>WS: broadcast update_status
        WS->>Client: WS frame
        Client->>Client: syncFromPayload, render modal or badge
    else unchanged
        Sched->>Sched: skip broadcast
    end

Component Responsibilities

Component	Responsibility
server/lib/update-check.js	Pure function getUpdatesStatus(root?, { skipFetch? }). Runs every git call via execFile (no shell, 10s–120s timeouts). Branch- and fork-aware: prefers upstream over origin when both exist (standard fork convention), resolves <remote>/master//main//HEAD, reads the current branch and its tracked upstream, and shapes manual_command per situation: git pull --ff-only only when the local branch tracks the canonical ref; git fetch <remote> && git merge --ff-only <ref> for forks (local branch name matches canonical but tracks a different remote); git fetch <remote> only on a feature branch or detached HEAD. Non-git installs, missing remotes, fetch failures, and unresolvable upstream refs are returned as soft payloads — never throws. Adds situation, situation_note, canonical_remote, current_branch, tracking_upstream, and tracks_canonical to the response.
server/update-scheduler.js	Ticks the lib every DASHBOARD_UPDATE_CHECK_INTERVAL_MS (default 300 000, floor 60 000). First tick is scheduled 8s after server start with .unref() so it doesn't block shutdown. Broadcasts only when the fingerprint {update_available, remote_sha, commits_behind, fetch_error, manual_command} changes — manual_command is included so situation transitions (e.g. user switches branches, or adds an upstream remote) trigger a re-broadcast even when the SHA and commit count are unchanged. Emits a framed message to stdout on "up-to-date → behind" transitions, and only suggests "restart the dashboard" when the printed command actually rewrites the working tree. DASHBOARD_UPDATE_CHECK=0|false|off disables the scheduler entirely.
server/routes/updates.js	Two endpoints: GET /status (read-only check), POST /check (check + broadcast). Mounted under /api/*, so they ride the default loopback bind as their trust boundary and are gated by DASHBOARD_TOKEN when one is set. There is no POST /apply route.
UpdateNotifier.tsx	Modal. Hydrates from api.updates.status() on mount and mirrors the payload back into the local eventBus so the Sidebar can listen without a second git fetch. Subscribes to update_status WS frames for ongoing sync. Keeps dismissedSha in localStorage (agent-monitor-update-dismissed-sha) and in React state; a window event dashboard:reset-update-dismissal from the Sidebar clears both. ESC / backdrop click dismisses.
Sidebar.tsx	Always-visible "Check for updates" button in the footer. Subscribes to update_status (no own fetch). On click: clears dismissed SHA in localStorage, dispatches dashboard:reset-update-dismissal, then calls api.updates.check(). Visual state: emerald badge when update_available, amber when fetch_error, neutral otherwise.

Payload Shape

interface UpdateStatusPayload {
  git_repo: boolean;
  update_available: boolean;
  repo_root?: string;
  remote_ref?: string | null;          // "upstream/master" | "origin/main" | ...
  canonical_remote?: string | null;    // "upstream" preferred, else "origin"
  current_branch?: string | null;      // null on detached HEAD
  tracking_upstream?: string | null;   // e.g. "origin/feature/foo", null if no upstream
  tracks_canonical?: boolean;          // true when branch upstream === remote_ref
  situation?:                          // categorical hint for the UI
    | "tracking_canonical"
    | "fork_or_diverged_tracking"
    | "feature_branch"
    | "detached_head";
  situation_note?: string | null;      // human-readable explanation when not tracking_canonical
  local_sha?: string | null;
  remote_sha?: string | null;
  commits_behind?: number;
  manual_command?: string | null;      // shaped for the user's situation
  message?: string | null;
  fetch_error?: string;                // set when git fetch fails
}

The same shape is used by GET /status, POST /check, and the update_status WS message.

Failure Mode Matrix

Condition	Returned payload	User-visible effect
Not a git clone	{git_repo:false, update_available:false, message:"Install directory is not a git clone..."}	Modal suppressed (update_available false). Sidebar stays neutral.
No remotes configured	{git_repo:true, update_available:false, message:"No git remotes configured..."}	Same as above.
git fetch failed (offline, auth)	{git_repo:true, update_available:false, canonical_remote, fetch_error:"<stderr>"}	Sidebar button goes amber; modal stays suppressed until a successful check.
Canonical default branch unresolvable	{git_repo:true, update_available:false, canonical_remote, message:"Could not resolve <remote>/master..."}	Modal suppressed.
Healthy, up to date	{git_repo:true, update_available:false, commits_behind:0, situation:"tracking_canonical"|...}	Sidebar neutral, modal suppressed.
Healthy, behind, on canonical branch	{update_available:true, situation:"tracking_canonical", manual_command:"...git pull --ff-only..."}	Modal opens with git pull flow + restart hint.
Healthy, behind, fork (origin = fork, upstream = canonical)	{update_available:true, situation:"fork_or_diverged_tracking", manual_command:"...git fetch upstream && git merge --ff-only upstream/master..."}	Modal opens with merge flow + restart hint + situation_note explaining the divergence.
Healthy, behind, on a feature branch	{update_available:true, situation:"feature_branch", manual_command:"...git fetch <remote>"}	Modal opens; situation_note explains the user is off the canonical branch; restart hint suppressed because the working tree isn't being changed.

Why Detection-Only

The dashboard does not expose an apply/restart endpoint by design. A process cannot reliably replace itself without an external supervisor, and several real constraints make an in-process self-update path strictly worse than letting the user run two commands in a terminal:

• Supervisor ambiguity. npm run dev (concurrently), npm start, pm2, systemd, launchd, and Docker each need different restart logic; an in-process helper could only encode one of them and would silently mis-restart the rest.
• Silent failures. npm install / npm run build / port-release timing issues surface as a dead server with no user-facing feedback once the original process has exited.
• No rollback. A partial pull + install leaves a broken checkout with no atomic recovery — the working tree is mutated mid-flight.
• Branch coverage. Even with the situation-aware manual_command produced by the detection layer, an automatic apply would still need branch-aware integration (rebase vs merge vs switch) and merge-conflict handling. That belongs in the user's shell, not in a background daemon.

The detection layer carries all of the signal value: the dashboard tells the user when to update and exactly what to run; the user owns the how in their own shell.

---

Tabby Companion Subsystem

Tabby is a client-only floating cat companion that reacts to live session activity. It is purely additive UI: there is no server/backend code, no new API routes, no new WebSocket message types, and no database changes. Tabby reuses the existing real-time event stream (the same eventBus every page already consumes) and the existing Run page for its "ask a real question" path. The entire subsystem lives under client/src/components/Tabby/.

The design follows a strict pure-core / hook / presentational split: a framework-free brain (a WSMessage reducer plus a mood state machine with an injected clock and zero side effects) is fully unit-tested in isolation, a single React hook is the only consumer of the global eventBus and the only owner of timers and side effects, and the SVG/markup components are pure presentational views driven by props.

Module Layout

graph TD
    subgraph "Pure Core (framework-free, unit-tested)"
        BRAIN["brain.ts<br/>reduceTabby reducer +<br/>deriveMood state machine<br/>(injected clock, no side effects)"]
        INTENTS["intents.ts<br/>local Q&A over cached status;<br/>unmatched → Run handoff"]
        QUIPS["quips.ts<br/>mood → phrase pools"]
        PREFS["prefs.ts<br/>localStorage enabled/muted<br/>(cross-tab sync)"]
    end

    subgraph "Hook (only eventBus consumer)"
        HOOK["useTabbyBrain.ts<br/>wires brain to real timers<br/>(idle/sleep/stuck), speech-bubble<br/>queue, mute, clear-alerts"]
    end

    subgraph "Presentational (pure)"
        SHELL["Tabby.tsx<br/>shell: open/closed state,<br/>⌘B / Esc, reduced-motion,<br/>navigation"]
        AVATAR["CatAvatar.tsx<br/>SVG cat; data-mood drives CSS;<br/>cursor-tracking pupils"]
        BUBBLE["SpeechBubble.tsx<br/>bubble"]
        PANEL["TabbyPanel.tsx<br/>status + quick actions + Ask box"]
        CSS["tabby.css<br/>keyframes + per-mood expressions"]
    end

    BUS["lib/eventBus.ts<br/>(existing WS stream)"]

    BUS --> HOOK
    HOOK --> BRAIN
    HOOK --> QUIPS
    HOOK --> PREFS
    SHELL --> HOOK
    SHELL --> INTENTS
    SHELL --> AVATAR & BUBBLE & PANEL
    AVATAR --> CSS

    style BRAIN fill:#10b981,stroke:#34d399,color:#fff
    style BUS fill:#f59e0b,stroke:#fbbf24,color:#000
    style HOOK fill:#6366f1,stroke:#818cf8,color:#fff

Data Flow

flowchart LR
    WSS["Server WebSocket<br/>broadcast"] --> UWS["useWebSocket"]
    UWS --> PUB["eventBus.publish"]
    PUB --> SUB["useTabbyBrain<br/>(subscriber)"]
    SUB --> DERIVED["derived state<br/>{ mood, status, bubble }"]
    DERIVED --> AVATAR["CatAvatar"]
    DERIVED --> BUBBLE["SpeechBubble"]
    DERIVED --> PANEL["TabbyPanel"]
    PANEL -->|"unmatched Ask"| RUN["/run?prompt=…<br/>(existing Run page)"]

    style PUB fill:#f59e0b,stroke:#fbbf24,color:#000
    style RUN fill:#10b981,stroke:#34d399,color:#fff

The mood state machine in deriveMood resolves to a single expression using a fixed priority order: disconnected > worried > stuck > happy > thinking > watching > sleeping > idle. The resolved mood is written to a data-mood attribute on the SVG cat, and tabby.css maps each mood to its keyframe animation and expression.

Component Responsibilities

Component	Responsibility
brain.ts	Pure, framework-free core. Exposes a WSMessage reducer (reduceTabby) and a mood state machine (deriveMood) with the priority order disconnected > worried > stuck > happy > thinking > watching > sleeping > idle. The clock is injected and there are zero side effects, so the brain is fully unit-tested in isolation.
useTabbyBrain.ts	The only consumer of the global eventBus. Wires the pure brain to real timers (idle / sleep / stuck), the speech-bubble queue, mute, and clear-alerts. Produces the derived { mood, status, bubble } the presentational components render.
CatAvatar.tsx	Pure presentational SVG cat. The data-mood attribute drives CSS; pupils track the cursor.
SpeechBubble.tsx	Pure presentational speech bubble.
TabbyPanel.tsx	Pure presentational panel: status readout + quick actions + the Ask box.
Tabby.tsx	Shell component. Mounted once in client/src/components/Layout.tsx as a sibling of UpdateNotifier. Owns open/closed state, the ⌘B / Esc shortcuts, reduced-motion detection, and navigation.
intents.ts	Pure local Q&A over the cached status snapshot. Queries that don't match a local intent become a handoff to the existing Run page via /run?prompt=….
quips.ts	Pure mood → phrase pools.
prefs.ts	localStorage-backed enabled / muted preferences with cross-tab sync.
tabby.css	Keyframes and per-mood expressions; selected via the data-mood attribute.

Touchpoints Outside the Folder

Tabby's only contact with the rest of the app is four light, additive touchpoints — nothing in the server, database, or WebSocket protocol changes:

File	Touchpoint
client/src/components/Layout.tsx	Mounts <Tabby /> once, as a sibling of <UpdateNotifier />.
client/src/pages/Settings.tsx	On/off toggle wired to tabbyPrefs (localStorage).
client/src/pages/Workspace.tsx	Reads ?prompt= to prefill the prompt box for Tabby's Ask handoff.
client/src/i18n/locales/{en,zh,vi,ko}/settings.json	tabby.* strings for the Settings toggle (en / zh / vi / ko).

---

VS Code Extension Architecture

The Claude Code Agent Monitor VS Code extension provides an integrated monitoring experience directly within the editor. It communicates with the local dashboard server via standard HTTP APIs and renders the dashboard UI in a webview.

Extension Components

Component	Responsibility
Extension Host (extension.js)	Manages the extension lifecycle, registers commands, creates the status bar item, and coordinates the webview panel.
Sidebar Provider (sidebar.js)	Implements the TreeDataProvider for the Activity Bar. It performs background polling of the dashboard APIs (/api/stats, /api/analytics, /api/sessions) every 5 seconds.
Status Bar Item	Provides a persistent "Pulse" indicator in the VS Code status bar, showing active session and agent counts.
Webview Panel	A native VS Code tab that renders the dashboard React application. It supports deep linking to specific sessions or sub-pages.

Data Flow

graph TD
    subgraph "VS Code Process"
        SB[Status Bar]
        SIDE[Sidebar TreeView]
        WV[Webview Panel]
    end

    subgraph "Extension Host"
        EH[extension.js]
        SP[sidebar.js]
    end

    subgraph "Dashboard Server (localhost)"
        API["/api/stats<br/>/api/analytics<br/>/api/sessions"]
        DS[Express Server]
    end

    SIDE -->|Poll 5s| SP
    SP -->|HTTP GET| API
    EH -->|HTTP GET| API
    SB -->|Pulse| EH
    WV -->|Iframe src| DS

Key Implementation Details

1. Auto-Detection: The extension checks both port 5173 (Vite dev server) and 4820 (Production server) on localhost. It prioritizes the production port for API data but can render the UI from either.
2. Real-time Status: The SidebarProvider uses a background loop with onDidChangeTreeData to automatically toggle between Online and Offline states as the local server starts or stops.
3. Deep Linking: Commands like claude-code-agent-monitor.openDashboard accept arguments (e.g., a session ID or page path like analytics) to route the webview to specific views within the React SPA.
4. Theme Awareness: The Activity Bar icon (icon.svg or apple-touch-icon.png) and sidebar icons use VS Code's ThemeIcon and ThemeColor to ensure they adapt to Light, Dark, and High Contrast themes.

For the extension source code, refer to the vscode-extension/ directory.

Tip

Extension on VS Code Marketplace: Claude Code Agent Monitor

---

Desktop App Architecture (macOS & Windows / Electron)

The desktop/ workspace ships the dashboard as a native desktop app for macOS (Claude Code Monitor.app, distributed as a .dmg) and Windows (Claude Code Monitor.exe, distributed as an NSIS installer plus a no-install portable build). It is an Electron shell that embeds the existing Express server in-process and renders the already-built React client in a BrowserWindow. The desktop app does not reimplement the dashboard -- it require()s server/index.js directly, in the same Node runtime as the Electron main process, and points a Chromium window at it.

For the user-facing guide (download, install, Gatekeeper / SmartScreen, tray menu, auto-start), see DESKTOP.md. For the full contributor/architecture reference -- including build performance, code signing, notarization, and CI details -- see desktop/README.md.

Workspace Position

desktop/ is a sibling workspace, not an npm-workspaces conversion. It has its own package.json, its own node_modules, and its own TypeScript toolchain. It pins Electron 35 (bundled Node 22.16). It consumes the rest of the repo as plain files and touches no other workspace's runtime behavior.

flowchart TD
    subgraph repo["Claude-Code-Agent-Monitor (repo root)"]
        server["server/<br/>Express API · SQLite · WebSocket"]
        client["client/<br/>React + Vite SPA"]
        scripts["scripts/<br/>hook installer/handler, import, seed"]
        mcp["mcp/<br/>local MCP server"]
        vscode["vscode-extension/"]
        desktop["desktop/<br/>Electron shell (sibling workspace)"]
    end

    desktop -->|"require() in-process"| server
    desktop -->|"loads built SPA from"| client
    desktop -->|"auto-installs hooks via"| scripts
    server -->|"serves static"| client

    style desktop fill:#1f6feb,stroke:#1158c7,color:#fff
    style server fill:#238636,stroke:#196c2e,color:#fff

The only change outside desktop/ is a behavior-preserving refactor of server/index.js (see Background Services & Hook Bootstrap below). client/, scripts/, mcp/, and vscode-extension/ are untouched.

Process Model

Electron runs a main process (Node.js) and one or more renderer processes (Chromium). In this app:

• The main process hosts the embedded Express server and manages the window, tray, and menus. There is no child process and no IPC for the server -- it runs inside the main process's own event loop.
• The renderer is plain Chromium loading http://127.0.0.1:<port> -- exactly the same origin a normal browser would use. preload.ts is intentionally empty (contextIsolation: true, nodeIntegration: false, webSecurity: true), so the renderer has zero privileged surface.

flowchart LR
    subgraph main["Electron Main Process (Node 22 / Electron 35)"]
        boot["main.ts<br/>lifecycle"]
        host["server-host.ts<br/>embedded server"]
        express["server/index.js<br/>Express + WS + SQLite"]
        tray["tray.ts"]
        menu["menu.ts"]
        host --> express
        boot --> host
        boot --> tray
        boot --> menu
    end

    subgraph renderer["Renderer Process (Chromium)"]
        win["BrowserWindow<br/>React dashboard"]
        preload["preload.ts<br/>(empty -- no bridge)"]
    end

    express -->|"http + ws on 127.0.0.1:port"| win
    win -.->|loads| preload

    hooks["Claude Code hooks<br/>(separate node processes)"] -->|"POST /api/hooks/event"| express

    style main fill:#0d1117,stroke:#30363d,color:#e6edf3
    style renderer fill:#161b22,stroke:#30363d,color:#e6edf3

In-Process Server Hosting

server-host.ts is the only file that imports server/index.js. The dashboard server already exports { createApp, startServer, startBackgroundServices } and serves the built React client (client/dist) as static assets in production -- so the host imports that module directly, with no child process, no IPC, and no port marshalling.

Component	Responsibility
main.ts	Main-process entry. Single-instance lock, app menu + tray wiring, dashboard window, Restart Server, lifecycle (window-all-closed, before-quit).
server-host.ts	In-process Express boot: port discovery, adoption, better-sqlite3 ABI patch, startBackgroundServices() + hook bootstrap, clean DB close. Returns a ServerHandle.
window.ts	BrowserWindow with persisted geometry (userData/window-state.json). External links open in the system browser. Sets the window/taskbar icon to the colored app logo (assets/icon.ico on Windows, icon.png elsewhere) so an unpackaged desktop:dev run no longer shows the generic Electron icon.
menu.ts / tray.ts	Native application menu and menu-bar / notification-area (tray) icon. tray.ts selects a platform tray image — a macOS template glyph that the OS tints for the menu bar, or the colored assets/icon.ico for the Windows notification area (a black template would vanish on the dark taskbar). Tray uses a single-click dropdown (left or right) with a live status snapshot queried straight from SQLite at click time — server port, active sessions, working agents, events today — followed by Open Dashboard, Open in Browser, Restart Server, Show Logs, Open at Login (toggle), and Quit. The menu is rebuilt on each open so every value stays current. Snapshot rows are enabled and click-to-open-dashboard rather than disabled (which the OS dims). The application menu's File ▸ Open Dashboard (⌘1) is macOS-only — there the global menu bar persists after the window hides; on Windows/Linux the window-attached menu can't reopen a hidden window, so reopening is the tray's job. focusOrCreateWindow calls show() unconditionally so the tray reliably raises a backgrounded/minimized window (a bare focus() on Windows often only flashes the taskbar).
login-item.ts	Auto-start-at-login toggle through Electron's first-party app.setLoginItemSettings API on every platform. On macOS it drives the modern SMAppService Login Items (not a LaunchAgent plist); on Windows it writes a per-user HKCU\Software\Microsoft\Windows\CurrentVersion\Run entry. Login launches are tagged with a --ccam-hidden arg so the app can stay tray-only at startup — Windows has no wasOpenedAtLogin signal, so the arg is the cross-platform detection mechanism.
shell-path.ts	(macOS) Recovers the user's login-shell PATH at startup and merges it onto process.env.PATH, so the embedded server (and the claude CLI it spawns) is not limited to launchd's minimal PATH. On Windows the process already inherits the full user PATH, so no recovery is needed.
logger.ts	File logger to ~/Library/Logs/Claude Code Monitor/desktop.log (macOS) or %APPDATA%\Claude Code Monitor\logs\desktop.log (Windows) -- the main process has no console when launched from Finder / Explorer.
constants.ts	Shared identifiers, including the APP_ID (com.vn.smartgift.ccam.desktop) that main.ts sets as the Windows AppUserModelId.

server-host.ts resolves the directory containing the bundled server/ and client/dist/ via resolveAppRoot(): process.resourcesPath/app when packaged, or the repo root (one directory up from desktop/) in development.

The ServerHandle returned to main.ts:

interface ServerHandle {
  url: string; // e.g. "http://127.0.0.1:4820"
  port: number;
  ownedByUs: boolean; // false when an existing server was adopted
  stop: () => Promise<void>;
}

Port Discovery & Adoption

On startup server-host.ts picks a port, then either adopts an already-healthy server or boots its own. Adoption -- probePort() connects to :4820, then checks that the listener answers GET /api/health with { status: "ok" }. If a healthy dashboard server is already running there (e.g. the user ran npm start in a terminal), the desktop app adopts it rather than double-binding -- no SQLite contention. An adopted server is not owned by the app, so quitting the app leaves it running.

flowchart TD
    start["startEmbeddedServer()"] --> forced{"CCAM_DESKTOP_BIND_PORT set?"}
    forced -->|yes| bind["bind exactly that port<br/>(no adoption, no fallback)"]
    forced -->|no| adopt{"healthy server<br/>already on :4820?"}
    adopt -->|yes| reuse["adopt it<br/>ownedByUs = false"]
    adopt -->|no| pick["pickFreePort()"]

    pick --> p1{":4820 free?"}
    p1 -->|yes| use4820["use 4820"]
    p1 -->|no| p2{"any of<br/>:4821–:4829 free?"}
    p2 -->|yes| usefb["use that"]
    p2 -->|no| p3{"any of<br/>:49152–:49500 free?"}
    p3 -->|yes| userand["use that"]
    p3 -->|no| fail["throw — no free port"]

    bind --> bootsrv["createApp() + startServer()"]
    use4820 --> bootsrv
    usefb --> bootsrv
    userand --> bootsrv
    bootsrv --> healthy["waitForHealthy()<br/>poll /api/health ≤ 30s"]
    healthy --> bg["bootstrapOwnedServer()"]
    bg --> handle["ServerHandle ownedByUs = true"]
    reuse --> handleR["ServerHandle ownedByUs = false"]

    style reuse fill:#9e6a03,stroke:#7d5300,color:#fff
    style fail fill:#da3633,stroke:#b62324,color:#fff

Port preference order is 4820 → 4821–4829 → a random port in 49152–49500. Two environment overrides exist primarily for testing: CCAM_DESKTOP_BIND_PORT binds an exact port (disabling adoption and fallback, used by the smoke test), and CCAM_DESKTOP_NO_ADOPT=1 always starts a fresh server. Before require()ing the server module, the host sets NODE_ENV=production, DASHBOARD_PORT=<port>, and DASHBOARD_DATA_DIR=<userData>/data (see Writable Data Directory below) so the server reads them from process.env.

Writable Data Directory

A packaged install directory is read-only in practice: on macOS a .app bundle installed under /Applications, code-signed, or run through app translocation cannot write to Resources/app/, and on Windows the NSIS install dir under %ProgramFiles% (or the read-only mount a portable build runs from) is no place for mutable state. The dashboard's SQLite database and the VAPID keypair (server/lib/push.js) are writable state, so they must not live inside the bundle / install dir. Before booting the embedded server, server-host.ts creates app.getPath('userData')/data and points the server at it via the DASHBOARD_DATA_DIR environment variable:

• server/db.js honors DASHBOARD_DATA_DIR for the SQLite file.
• server/lib/push.js honors it for the persisted VAPID keys.

The resulting per-user location is ~/Library/Application Support/Claude Code Monitor/data/ on macOS and %APPDATA%\Claude Code Monitor\data\ on Windows. Because this lives outside the bundle / install dir, imported history and persisted events survive an app reinstall or update (the Windows NSIS uninstaller keeps this data by default). Without this, writing a database into the read-only install location failed on a packaged build and broke History Import and event persistence.

The standalone node server/index.js path is unaffected: DASHBOARD_DATA_DIR is unset there, and server-host.ts only sets it when it is not already defined -- so server/db.js falls back to its usual repo-relative default.

Shell PATH Recovery (macOS)

This step is macOS-only. A macOS app launched from Finder, the Dock, or Login Items auto-start is spawned by launchd, which hands it a minimal PATH (roughly /usr/bin:/bin:/usr/sbin:/sbin) and does not source the user's shell profile. The dashboard's "Run Claude" feature (server/routes/run.js, server/lib/run-spawner.js) spawns the claude CLI, which is almost always installed somewhere only the shell PATH knows about (/opt/homebrew/bin, ~/.local/bin, ~/.claude/local, a Node version-manager's bin dir). Under launchd's PATH, claude cannot be resolved or spawned.

shell-path.ts repairs this before the server boots: at startup it runs the user's login+interactive shell once ($SHELL -ilc, so .zprofile/.zshrc are sourced), captures the resulting PATH between sentinel markers, and merges it -- plus a fallback list of common CLI install directories -- onto process.env.PATH. The merge is order-preserving and deduplicated, so it is idempotent. Because the embedded server runs in the same process, it and every claude it spawns inherit the corrected PATH. (A claude shell alias or function still cannot be spawned -- only a real executable on the PATH can.)

On Windows there is no equivalent step: a process launched from Explorer, the Start menu, or the HKCU\…\Run startup entry already inherits the full user PATH, so the embedded server can resolve claude directly.

better-sqlite3 Native-Module Handling

better-sqlite3 is the only native module in the dependency tree, and a native module must be compiled against the exact Node ABI it runs on. The repo-root copy is built for the system Node (so npm run test:server works for contributors); Electron ships its own Node ABI.

The desktop workspace solves this without disturbing the root install: the desktop workspace has its own better-sqlite3, rebuilt for Electron's Node ABI by electron-builder install-app-deps (run in its postinstall). server-host.ts then installs a one-time, process-local patch to Module._resolveFilename that redirects require("better-sqlite3") -- from anywhere in the embedded server -- to that ABI-correct copy.

Desktop setup is guarded so a missing or unbuilt binary never escapes as a raw node-gyp trace or a runtime crash: desktop/scripts/preflight.js (shared by install.js and prebuild.js) verifies the Electron-ABI binary exists and, when it doesn't, prints actionable, copy-pasteable setup help -- the per-OS C++ toolchain prerequisites (or a no-toolchain alternative that fetches Electron's prebuilt binary directly) -- before exiting non-zero. desktop:install runs this on install; the prebuild gate enforces it before every desktop:* build, turning a would-be runtime failure into a build-time error.

flowchart TD
    subgraph desk["desktop/node_modules"]
        d1["better-sqlite3<br/>rebuilt for Electron's ABI<br/>(electron-builder install-app-deps)"]
    end
    subgraph root["node_modules (repo root)"]
        r1["better-sqlite3<br/>built for system Node<br/>(used by npm run test:server)"]
    end

    patch["ensureNativeModulesPatched()<br/>overrides Module._resolveFilename"]
    srv["server/db.js<br/>require('better-sqlite3')"]

    srv -->|"request intercepted"| patch
    patch -->|"redirected to"| d1
    patch -.->|"everything else<br/>passes through"| root

    style d1 fill:#238636,stroke:#196c2e,color:#fff
    style patch fill:#1f6feb,stroke:#1158c7,color:#fff

• The patch is installed exactly once, before server/index.js is require()d, and rewrites only require("better-sqlite3") -- every other module resolves normally.
• electron-builder.yml therefore excludes the root better-sqlite3 from the bundle (it would trip @electron/universal's identical-file detector) and asarUnpacks the desktop copy (native .node files cannot live inside an asar archive).
• The compat-sqlite (node:sqlite) fallback remains a safety net -- one reason the desktop app pins Electron 35, whose bundled Node 22.16 has node:sqlite.

Background Services & Hook Bootstrap

node server/index.js runs its production bootstrap from an if (require.main === module) block. Because the desktop app require()s that module, the block never fires -- so the bootstrap was extracted into an exported startBackgroundServices() that both paths call. This is a behavior-preserving refactor of server/index.js: the standalone server path is functionally unchanged.

flowchart LR
    subgraph standalone["node server/index.js"]
        s1["require.main === module"] --> s2["startBackgroundServices()"]
    end
    subgraph desktopapp["desktop app"]
        d1["server-host.ts<br/>bootstrapOwnedServer()"] --> d2["startBackgroundServices()"]
        d1 --> d3["installHooks()"]
    end

    d2 --> svc
    s2 --> svc
    subgraph svc["Background services"]
        u["update scheduler"]
        w["cc-watcher (Claude config watcher)"]
        r["orphaned-run reconciliation"]
    end

    style d1 fill:#1f6feb,stroke:#1158c7,color:#fff

bootstrapOwnedServer() runs once -- guarded by a module-level flag so a Restart Server does not double-register schedulers or watchers -- and:

1. Calls startBackgroundServices() -- the update scheduler, the cc-watcher config watcher, and one-time orphaned-run reconciliation.
2. Calls installHooks() -- writes the Claude Code hook configuration to ~/.claude/settings.json, so an install-only user (DMG on macOS, .exe on Windows) gets events flowing without ever running npm run install-hooks from a checkout.

It runs only when the server is owned by the app -- an adopted server has already done its own bootstrap.

App Lifecycle

sequenceDiagram
    autonumber
    participant OS as macOS / Windows
    participant Main as main.ts
    participant Host as server-host.ts
    participant Srv as server/index.js
    participant UI as BrowserWindow

    OS->>Main: launch app
    Main->>Main: setAppUserModelId (win32) · requestSingleInstanceLock()
    alt lock not acquired
        Main->>OS: exit(0) — focus existing instance
    end
    Main->>Host: ensureUserPath() — recover login-shell PATH (macOS only)
    Main->>Host: startEmbeddedServer()
    Host->>Host: probe :4820 — adopt if a healthy server answers
    alt no server to adopt
        Host->>Host: pickFreePort() · set DASHBOARD_DATA_DIR · patch better-sqlite3 ABI
        Host->>Srv: require() · createApp() · startServer(port)
        Host->>Srv: waitForHealthy() — poll /api/health ≤ 30s
        Host->>Srv: bootstrapOwnedServer() — schedulers, cc-watcher, install hooks
    end
    Host-->>Main: ServerHandle { url, port, ownedByUs, stop }
    Main->>Main: installApplicationMenu() · createTray()
    alt launched at login (--ccam-hidden / wasOpenedAtLogin)
        Main->>OS: stay tray-only, hide dock (macOS)
    else normal launch
        Main->>UI: createDashboardWindow(url)
        UI->>Srv: GET http://127.0.0.1:port
    end
    Note over Main: window "close" → hide (server keeps running)
    Note over Main: ⌘Q / Ctrl+Q → confirm (second press bypasses)
    Note over Main: before-quit → stop owned server + closeEmbeddedDatabase()

Event	Behavior
Second launch	requestSingleInstanceLock() (enabled on every platform) fails -- the new process exits and the existing window is focused.
Window close	Intercepted -- the window hides (hide()); the server and tray keep running.
window-all-closed	App stays alive in tray-only mode (the handler is intentionally a no-op).
Launched at login	The dashboard window is not shown -- only the tray icon. Detected via macOS wasOpenedAtLogin (dock hidden, openAsHidden) or, on Windows, the --ccam-hidden arg written into the HKCU\…\Run startup command.
Quit shortcut	⌘Q (macOS) / Ctrl+Q (Windows) shows a confirmation dialog; a second press bypasses it.
before-quit	If the server is owned: stop the HTTP server, then closeEmbeddedDatabase() for a clean WAL checkpoint, then app.exit(0). The DB handle is closed here -- never on Restart Server, where the cached server/db.js singleton must stay usable.

Packaged App Layout

electron-builder produces Claude Code Monitor.app on macOS and Claude Code Monitor.exe (NSIS installer + portable) on Windows. On both platforms the Electron main-process code is compiled (tsc → out/) and packed into app.asar; the rest of the repo is shipped as extraResources -- plain files under the bundle's Resources/app/ (macOS) or the install dir's resources\app\ (Windows). The internal layout is the same shape on both:

flowchart TD
    appbundle["Claude Code Monitor.app (macOS)<br/>Claude Code Monitor install dir (Windows)"]
    appbundle --> contents["Contents/ (macOS)<br/>install root (Windows)"]
    contents --> macos["MacOS/ — Electron binary (macOS)<br/>Claude Code Monitor.exe (Windows)"]
    contents --> res["Resources/ (macOS)<br/>resources\ (Windows)"]
    res --> asar["app.asar<br/>(compiled out/**, package.json)"]
    res --> unpacked["app.asar.unpacked/<br/>node_modules/better-sqlite3 (.node)"]
    res --> appdir["app/"]
    appdir --> a1["server/   — Express server (no tests)"]
    appdir --> a2["client/dist/ — built React SPA"]
    appdir --> a3["scripts/  — hook-handler, install-hooks"]
    appdir --> a4["node_modules/ — server runtime deps"]
    appdir --> a5["package.json"]

    style asar fill:#1f6feb,stroke:#1158c7,color:#fff
    style appdir fill:#238636,stroke:#196c2e,color:#fff

At runtime server-host.ts resolves this root as process.resourcesPath/app when packaged, on both platforms. Everything under the packaged app/ is read-only on a packaged, signed, or app-translocated macOS bundle and on a Windows install under %ProgramFiles% (or a portable build's mount) -- so all writable state (the SQLite database, VAPID keys) lives in the per-user data dir (~/Library/Application Support/Claude Code Monitor/data/ on macOS, %APPDATA%\Claude Code Monitor\data\ on Windows), never inside the bundle / install dir (see Writable Data Directory).

On macOS electron-builder produces two per-architecture DMGs — one arm64 (Apple Silicon), one x64 (Intel) — via --mac --arm64 --x64 (not a merged universal binary; the release ships both), ad-hoc signed by default so anyone can build a working .dmg without a paid Apple Developer account; real Developer ID signing and notarization are opt-in via environment variables (CSC_LINK, APPLE_ID, etc.). On Windows it produces an NSIS installer .exe and a no-install portable .exe (both x64), using assets/icon.ico (generated from the source PNG by desktop/scripts/build-win-icon.ps1) as the application and tray icon. electron-builder packages for the host OS -- DMGs build on macOS, Windows .exes build on Windows -- so the two artifacts come from two CI jobs (see below). The desktop/scripts/prebuild.js guard also self-heals a better-sqlite3 native binary that a prior cross-arch DMG build (electron-builder --mac --x64/--arm64) left compiled for the wrong CPU architecture -- it detects the mismatch via file and re-runs electron-builder install-app-deps, so desktop:dev and desktop:test do not fail with ERR_DLOPEN_FAILED; on Windows it shells the .cmd shims for npm/npx. CI runs a path-filtered 🍎 macOS Desktop (DMG) job on macos-latest (artifact ClaudeCodeMonitor-dmg) and a 🪟 Windows Desktop (EXE) job on windows-latest (artifact ClaudeCodeMonitor-win); the release attaches both. See desktop/README.md for the full build pipeline, build-performance notes, and signing details.

Relation to Standalone Deployment

The desktop app is a fourth deployment mode alongside Development, Production, and Container (see Deployment Modes). The data path is identical to the standalone Production path -- Claude Code hooks POST /api/hooks/event to the embedded Express server, which writes to SQLite and broadcasts over WebSocket to the renderer. The only structural difference is that the server runs inside the Electron main process instead of a standalone node server/index.js, and the renderer is a BrowserWindow rather than a browser tab pointed at the same origin.

---

Security Considerations

Area	Approach
SQL injection	All queries use prepared statements with parameterized values
Request size	Express JSON body parser limited to 1MB
Input validation	Required fields checked before database operations; CHECK constraints on status enums
Hook safety	Hook handler always exits 0; 5s max lifetime; uses 127.0.0.1 not external hosts
CORS	Loopback-only (corsOptions() in server/lib/security.js): cross-origin pages can't read responses; No-Origin requests (curl/CLI) still pass. The legacy Access-Control-Allow-Origin: * via bare cors() is gone
Network posture	Server binds 127.0.0.1 (loopback) by default — not network-reachable out of the box (fix for GHSA-gr74-4xfh-6jw9; it previously bound 0.0.0.0 with no auth). Widen the bind via DASHBOARD_HOST (e.g. 0.0.0.0), which logs a startup warning. A Host-header allowlist on HTTP + WebSocket upgrades blocks DNS-rebinding; extra LAN names go in DASHBOARD_ALLOWED_HOSTS (comma-separated)
Auth (optional)	Off by default — the loopback bind is the trust boundary. Set DASHBOARD_TOKEN to gate every /api/* request and the WebSocket, presented as Authorization: Bearer <token>, an x-dashboard-token header, or ?token=. Exempt even when set: /api/health, /api/openapi.json, /api/docs, and /api/hooks (local Claude Code hook ingestion)
No secrets	No API keys, tokens, or credentials stored or transmitted
Dependency surface	Minimal: 5 runtime server deps, 6 runtime client deps (includes d3 and d3-sankey for Workflows visualizations)

---

Performance Characteristics

Metric	Value	Notes
Server startup	< 200ms	SQLite opens instantly; schema migration is idempotent
Hook latency	< 5ms (cache hit), < 50ms (miss)	TranscriptCache: stat-check only on cache hit; incremental byte-offset read on file growth; full read only on first contact or compaction
Client bundle	200 KB JS, 17 KB CSS	Gzipped: ~63 KB JS, ~4 KB CSS
WebSocket latency	< 5ms	Local loopback, JSON serialization only
SQLite write throughput	~50,000 inserts/sec	WAL mode on SSD; far exceeds hook event rate
Max events before slowdown	~1M rows	SQLite handles this easily; pagination prevents full-table scans
Memory usage	~30 MB server, ~15 MB client	SQLite in-process, no ORM overhead. TranscriptCache adds ~1 KB per active session (LRU-capped at 200 entries)

SQLite WAL Mode Benefits

graph LR
    subgraph "Without WAL"
        W1[Writer] -->|blocks| R1[Reader]
    end

    subgraph "With WAL"
        W2[Writer] --- R2[Reader]
        Note["Concurrent reads<br/>during writes"]
    end

    style Note fill:#10b981,stroke:#34d399,color:#fff

---

Deployment Modes

Development

graph LR
    subgraph "Terminal"
        DEV["npm run dev<br/>(concurrently)"]
    end

    DEV --> SERVER["node --watch server/index.js<br/>Port 4820<br/>Auto-restart on changes"]
    DEV --> VITE["vite dev server<br/>Port 5173<br/>HMR, proxies /api + /ws to 4820"]
    BROWSER["Browser"] --> VITE
    VITE -->|proxy| SERVER

    style VITE fill:#646CFF,stroke:#818cf8,color:#fff
    style SERVER fill:#339933,stroke:#5cb85c,color:#fff

Production

graph LR
    BUILD["npm run build<br/>(vite build in client/)"] --> DIST["client/dist/<br/>Static files"]
    START["npm start"] --> SERVER["node server/index.js<br/>Port 4820"]
    SERVER -->|serves| DIST
    BROWSER["Browser"] --> SERVER

    style SERVER fill:#339933,stroke:#5cb85c,color:#fff
    style DIST fill:#646CFF,stroke:#818cf8,color:#fff

Aspect	Development	Production
Processes	2 (Express + Vite)	1 (Express)
Client	Vite HMR on :5173	Static files from client/dist
API proxy	Vite proxies /api + /ws to :4820	Same origin, no proxy needed
File watching	node --watch + Vite HMR	None
Source maps	Inline	External files

Desktop App (macOS & Windows)

The native desktop app (macOS .app/.dmg, Windows NSIS / portable .exe) is a self-contained deployment mode: a single Electron process embeds the Express server in-process and renders the React client in a BrowserWindow. No terminal, no separate npm start.

graph LR
    LAUNCH["Open Claude Code Monitor<br/>(.app / .exe)"] --> MAIN["Electron main process<br/>(Node 22 / Electron 35)"]
    MAIN --> HOST["server-host.ts<br/>port discovery + adopt"]
    HOST --> SERVER["server/index.js (in-process)<br/>Port 4820 → fallback"]
    SERVER -->|serves| DIST["client/dist/<br/>(extraResources)"]
    MAIN --> WIN["BrowserWindow"]
    WIN --> SERVER

    style MAIN fill:#1f6feb,stroke:#1158c7,color:#fff
    style SERVER fill:#339933,stroke:#5cb85c,color:#fff
    style DIST fill:#646CFF,stroke:#818cf8,color:#fff

The hook ingestion path (Claude Code hooks → POST /api/hooks/event → SQLite → WebSocket) is identical to the standalone Production path -- only the process that hosts the server differs. See Desktop App Architecture for the full design.

MCP Sidecar (Optional)

The MCP server runs as a sidecar alongside the dashboard, connecting to the same API. It supports three transport modes:

graph LR
    subgraph "MCP Transports"
        M_STDIO["stdio\nnpm run mcp:start"]
        M_HTTP["HTTP+SSE\nnpm run mcp:start:http\n:8819"]
        M_REPL["REPL\nnpm run mcp:start:repl"]
    end

    HOST["MCP Host"] -->|"stdin/stdout"| M_STDIO
    RC["Remote Client"] -->|"POST /mcp · GET /sse"| M_HTTP
    OP["Operator"] -->|"interactive CLI"| M_REPL

    M_STDIO --> API["Dashboard API<br/>:4820"]
    M_HTTP --> API
    M_REPL --> API

    style M_STDIO fill:#0f766e,stroke:#14b8a6,color:#fff
    style M_HTTP fill:#0f766e,stroke:#14b8a6,color:#fff
    style M_REPL fill:#0f766e,stroke:#14b8a6,color:#fff

Command	Purpose
npm run mcp:install	Install MCP package dependencies
npm run mcp:build	Compile MCP server to mcp/build/
npm run mcp:start	Start MCP server (stdio, for MCP hosts)
npm run mcp:start:http	Start MCP HTTP+SSE server on port 8819
npm run mcp:start:repl	Start interactive MCP REPL
npm run mcp:dev	Run MCP server in dev mode (stdio, tsx)
npm run mcp:dev:http	Run MCP HTTP server in dev mode (tsx)
npm run mcp:dev:repl	Run MCP REPL in dev mode (tsx)
npm run mcp:typecheck	Type-check MCP source
npm run mcp:docker:build	Build MCP container image with Docker
npm run mcp:podman:build	Build MCP container image with Podman

Container (Docker / Podman)

A multi-stage Dockerfile builds the client and server into a single production image. Both Docker and Podman are fully supported — the image is OCI-compliant.

graph LR
    subgraph "Multi-Stage Build"
        S1["Stage 1: server-deps\nnode:22-alpine\nnpm ci --omit=dev"]
        S2["Stage 2: client-build\nnode:22-alpine\nnpm ci + vite build"]
        S3["Stage 3: runtime\nnode:22-alpine\nCopies node_modules + client/dist"]
        S1 --> S3
        S2 --> S3
    end

    subgraph "Container Runtime"
        VOL1["~/.claude (ro)\nlegacy session import"]
        VOL2["agent-monitor-data\nSQLite persistence"]
        S3 -->|"EXPOSE 4820"| SRV["node server/index.js\nport 4820"]
        VOL1 --> SRV
        VOL2 --> SRV
    end

    style S3 fill:#339933,stroke:#5cb85c,color:#fff
    style SRV fill:#6366f1,stroke:#818cf8,color:#fff

Usage:

# Docker Compose
docker compose up -d --build

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

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

Note

Hook note: Claude Code hooks run on the host, not inside the container. The containerized server still receives hook events via HTTP on localhost:4820 — run npm run install-hooks on the host after the container is up. scripts/install-hooks.js detects container execution and refuses there (issue #193) so it cannot write a container-internal handler path into a bind-mounted host ~/.claude; the containerized server's boot-time auto-install is skipped for the same reason. Override with CCAM_ALLOW_CONTAINER_HOOKS=1 only when Claude Code itself runs inside the container.

Cloud Deployment

For production cloud deployments, the deployments/ directory provides enterprise-grade infrastructure supporting four cloud providers and multiple deployment strategies.

graph TB
  subgraph "Deployment Pipeline"
    direction LR
    CI["CI Pipeline<br/>Build · Test · Scan"] --> DEPLOY["Deployment<br/>Helm · Kustomize · Terraform"]
    DEPLOY --> VERIFY["Verification<br/>Health Check · Smoke Tests"]
    VERIFY -->|Fail| ROLLBACK["Rollback<br/>Instant Revert"]
  end

  subgraph "Infrastructure"
    direction TB
    subgraph "Compute"
      BLUE["Blue Slot<br/>Current Version"]
      GREEN["Green Slot<br/>New Version"]
    end
    LB["Load Balancer<br/>TLS 1.3 · WebSocket<br/>Weighted Routing"]
    PV["Persistent Storage<br/>Encrypted NFS"]
    MON["Monitoring<br/>Prometheus · Grafana<br/>13 Alert Rules"]
    OTEL["OTel Collector<br/>Coralogix"]
  end

  LB -->|"Active"| BLUE
  LB -.->|"Standby"| GREEN
  BLUE & GREEN --> PV
  MON -->|"Scrape"| BLUE & GREEN
  BLUE & GREEN -->|"logs + metrics + traces"| OTEL

  style BLUE fill:#2563eb,color:#fff
  style GREEN fill:#16a34a,color:#fff
  style LB fill:#7c3aed,color:#fff
  style CI fill:#2088ff,color:#fff
  style OTEL fill:#4f46e5,color:#fff

Capability	Details
Cloud Providers	AWS (ECS Fargate + ALB), GCP (Cloud Run + GCLB), Azure (ACI + App Gateway), OCI (OKE + LBaaS)
Deployment Methods	Helm chart, Kustomize overlays, Terraform modules
Release Strategies	Rolling update, blue-green (instant switchover), canary (automated analysis)
Environments	Dev, staging, production with per-environment configuration
CI/CD	GitHub Actions and GitLab CI pipelines with Trivy security scanning
Observability	Prometheus scraping, 13 alert rules, Grafana dashboard (16 panels), Alertmanager routing, Coralogix full-stack observability (logs, metrics, traces, SLO tracking) via OpenTelemetry Collector
Operations	Scripts for deploy, rollback, blue-green switch, database backup/restore, teardown
Security	Restricted PSS, network policies, TLS enforcement, OIDC auth, no long-lived credentials

Note

📘 Full guide: See DEPLOYMENT.md for step-by-step deployment instructions, and deployments/README.md for the infrastructure technical reference.

---

Statusline Utility

The statusline/ directory contains a standalone CLI statusline for Claude Code, separate from the web dashboard. It renders a color-coded bar at the bottom of the Claude Code terminal showing model, user, working directory, git branch, context window usage, per-direction token counts, and session cost in USD.

Model Name Formatting (Client)

The client/src/lib/format.ts module exports a formatModelName() utility that converts raw model identifiers stored in the database into human-readable display names throughout the UI (everywhere except the Settings page, which shows raw patterns for pricing rule configuration).

Transformation rules:

Raw identifier	Formatted display
claude-opus-4-7-20260101	Claude Opus 4.7
claude-sonnet-4-5-20250514	Claude Sonnet 4.5
claude-haiku-3-5-latest	Claude Haiku 3.5
claude-opus-4-7[1m]	Claude Opus 4.7 (1M)
gpt-4o-mini	GPT-4o Mini
gemini-1-5-pro	Gemini 1.5 Pro
anthropic/claude-opus-4-7	Claude Opus 4.7

The function handles:

• Provider prefix stripping (anthropic/, openai/)
• Date suffix removal (-YYYYMMDD)
• -latest suffix removal
• Context-window tag extraction ([1m] → (1M))
• Brand capitalization (Claude, GPT, Gemini)
• Version number dot-joining (hyphen-separated digits → dotted)
• Title-casing for word segments

Components that consume this: SessionDetail, Analytics (donut chart + breakdown), Dashboard (model stats), MessageList, SessionCard, AgentCard, SessionComplexityScatter, SessionDrillIn, ModelDelegationFlow, and EventDetail.

Data Flow

sequenceDiagram
    participant CC as Claude Code
    participant SH as statusline-command.sh
    participant PY as statusline.py
    participant GIT as git CLI

    CC->>SH: stdin (JSON payload)
    SH->>PY: Pipes stdin through
    PY->>PY: Parse JSON (model, cwd, context_window, cost)
    PY->>GIT: git symbolic-ref --short HEAD
    GIT-->>PY: Branch name
    PY->>PY: Build ANSI-colored segments (incl. tokens by direction, cost)
    PY-->>CC: stdout (formatted statusline)

Segments

Segment	Source	Color Logic
Model	data.model.display_name	Always cyan
User	$USERNAME / $USER env var	Always green
Working Dir	data.workspace.current_dir	Always yellow, ~ prefix for home
Git Branch	git symbolic-ref --short HEAD	Always magenta, hidden outside git repos
Context Bar	data.context_window.used_percentage	Green < 50%, Yellow 50–79%, Red >= 80%
Token Counts	data.context_window.current_usage	Green ↑ input, cyan ↓ output, dim c cache reads
Session Cost	data.cost.total_cost_usd	Green < $5, Yellow $5–$20, Red >= $20 (shown on API and subscription plans)

Integration

The statusline is configured in ~/.claude/settings.json via the statusLine key:

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

Claude Code invokes this command on each update, piping a JSON payload to stdin. The script reads the JSON, extracts fields, runs git for branch info, and prints ANSI-formatted output to stdout.

Design decisions:

• Python 3.6+ -- available on virtually all systems, handles ANSI and JSON natively
• No dependencies -- uses only stdlib (sys, json, os, subprocess)
• Shell wrapper -- statusline-command.sh sets PYTHONUTF8=1 for Windows Unicode support and resolves the absolute path to the Python script
• Fail-safe -- exits silently on empty input or JSON parse errors, never blocks Claude Code

---

Technology Choices

Technology	Why This Over Alternatives
SQLite (via better-sqlite3 or built-in node:sqlite)	Zero-config, embedded, no server process. WAL mode gives concurrent reads. Synchronous API is simpler than async alternatives for this use case. Falls back to Node.js built-in node:sqlite when better-sqlite3 cannot be compiled
Express	Battle-tested, minimal, well-understood. Overkill would be Fastify for this scale; underkill would be raw http module
ws	Fastest, most lightweight WebSocket library for Node. No Socket.IO overhead needed since we only push JSON messages
React 18	Stable, widely known, strong TypeScript support. No need for Server Components or RSC given this is a client-rendered SPA
Vite	Fast builds, native ESM, excellent dev experience. Proxy config handles the dev server split cleanly
Tailwind CSS	Utility-first approach keeps styles colocated with markup. No CSS module boilerplate. Colors are CSS-variable-backed tokens (darkMode: "class") so the Dark/Light toggle re-themes the app with one class flip rather than per-component dark: variants
React Router 6	Standard routing for React SPAs. Layout routes with <Outlet> give clean shell composition
Lucide React	Tree-shakeable icon library. Only imports what's used (~20 icons)
TypeScript Strict	Catches null/undefined bugs at compile time. noUncheckedIndexedAccess prevents array bounds issues

---

Build & Run Targets

A root Makefile mirrors every npm script for developers who prefer make. Run make help for the full list.

make setup          Install all dependencies (root + client + MCP)
make dev            Start server + client in watch mode
make build          Build the React client for production
make start          Start the production server
make test           Run all tests (server + client)
make format         Format all files with Prettier
make mcp-build      Compile MCP TypeScript → JavaScript
make mcp-typecheck  Type-check MCP source without emitting
make docker-up      Start via docker-compose
make docker-down    Stop docker-compose stack

See Makefile for the complete set of 30 targets covering setup, dev, testing, formatting, MCP, data management, Codex extensions, and Docker/Podman workflows.