Architecture
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
| Part | Runs | Does |
|---|---|---|
ccdash emit, ask, tee | as Claude Code hooks and the statusline | hand each payload to the local collector; never fail Claude Code |
ccdash collector | a user service per machine | forwards to the hub, carries out what comes back, syncs ~/.claude |
ccdash hub | a system service, one per setup | keeps live state and history, serves the panel and the API, sends Web Push |
ccdash channel | an MCP server per session | delivers replies from the panel; exposes the knowledge tools |
ccdash report | the CLI | builds a report in the shared chrome; publishes one through the collector |
| DMS plugin | in DankMaterialShell | this 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 --allevery 5 s for liveness and background sessions, andclaude -p /usageevery 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/procevery 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 theccdash-webpackage) 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
~/.claudefiles and the knowledge notes, and reads the synced transcripts into a searchable catalog of past sessions (src/catalog/, its owncatalog.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.