Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Architecture

  1. Components
  2. What Claude Code interfaces are used
  3. The collector
  4. The hub
  5. Protocol

1. Components

on each workstation                      on the hub (always on)
Claude Code hooks ──► ccdash emit ─┐
prompts ────────────► ccdash ask ──┤
statusline ─────────► ccdash tee ──┼──► ccdash collector ══wss══► ccdash hub
claude agents --json ──────────────┤      │ (forwards, acts,      │ (state, SQLite,
claude -p /usage ──────────────────┤      │  syncs ~/.claude)     │  notifications)
niri window events ────────────────┘      └──► DMS plugin         ├──► web panel
                                                                  └──► Web Push
PartRunsDoes
ccdash emit, ask, teeas Claude Code hooks and the statuslinehand each payload to the local collector; never fail Claude Code
ccdash collectora user service per machineforwards to the hub, carries out what comes back, syncs ~/.claude
ccdash huba system service, one per setupkeeps live state and history, serves the panel and the API, sends Web Push
ccdash channelan MCP server per sessiondelivers replies from the panel; exposes the knowledge tools
ccdash reportthe CLIbuilds a report in the shared chrome; publishes one through the collector
DMS pluginin DankMaterialShellthis machine’s sessions in the bar and the dash

2. What Claude Code interfaces are used

Public ones only: claude agents --json, claude --bg, claude stop, claude rm, claude attach, claude daemon run, hooks, the statusline payload, channels, OpenTelemetry and the /usage report.

The one exception is the state sync: it copies the files Claude Code keeps under ~/.claude byte for byte and reads only the running-session registry (sessions/<pid>.json) and the prompt history’s lines; the transcript format is never parsed.

3. The collector

  • Takes hook events over a Unix datagram socket and forwards them to the hub over one WebSocket (/collect, a token per machine). While the hub is unreachable, events wait in an on-disk queue and Claude Code runs as if ccdash were not there.
  • Polls claude agents --json --all every 5 s for liveness and background sessions, and claude -p /usage every 10 minutes for the per-model weekly limits the statusline lacks (safe mode: no model request, no hooks, nothing saved; about a second of CPU).
  • Reads which skills Claude Code loads on the machine (the user’s, the plugins’, each workspace’s) every five minutes and tells the hub when they change, for the composer’s / menu.
  • Reads each session’s git branch from .git/HEAD (worktrees included) without running git, and its process tree’s CPU and memory (PSS) from /proc every 5 s.
  • Reports its machine every 30 s (uptime, CPU, memory, disks, battery, its wired cards for wake-on-LAN) and reconnects at once after a long sleep (machines).
  • Carries out what the hub sends: replies, prompt answers, renames, sessions to start, stop or open, sync work.
  • Serves a local API ($XDG_RUNTIME_DIR/ccdash/api.sock) for the hooks, the CLI and the DMS plugin, with a mirror of this machine’s sessions.

Claude Code reads hooks when a session starts: sessions that were running before ccdash was installed only show busy and idle until they are resumed.

The hooks answer Claude Code, too: a queued title, the knowledge the hub injects at a session start or prompt, the one-machine guard, and the stop of a turn interrupted from the panel: every main-thread tool hook asks the collector (one local round trip, in memory) whether an interrupt is pending and, if so, ends the turn (sessions).

4. The hub

  • One reducer per host turns events and polls into live session state; the history goes to SQLite (data).
  • Serves the panel (web/, built into the ccdash-web package) and the HTTP API under /api/v1, with server-sent events for live updates.
  • Sends Web Push for prompts and finished turns, with answer buttons.
  • Keeps the synced ~/.claude files and the knowledge notes, and reads the synced transcripts into a searchable catalog of past sessions (src/catalog/, its own catalog.db), which is what Sessions › Past and resuming a session the store never saw run use.
  • Keeps every node’s last report across restarts, reads its own machine, and sends wake-on-LAN magic packets (machines).

A conversation in the panel is rebuilt from hook events, so Claude’s thinking is not part of it.

5. Protocol

Collector and hub speak JSON messages over the WebSocket (src/protocol.rs). The protocol is versioned: a hub and a collector of different versions refuse each other and log why, so a hub and its collectors are upgraded together. The state sync uses plain HTTP routes under /sync/ with the collector’s token; the workspace sync uses git smart HTTP under /git/ with the same token (git http-backend behind the hub) and carries its configuration, unit states and conflict resolutions over the WebSocket (protocol 8). The collectors’ skill reports came with protocol 11, the desktop’s colours with protocol 12, the machine’s report, lock and suspend with protocol 13, the report note kind with protocol 14, drafts opened in an editor on a machine with protocol 15.