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

ccdash

A live dashboard for all your Claude Code sessions, on every machine: which are working, which wait for you, and what they did. A web panel for the phone and the desk, notes every session shares, and a hub that keeps them in step across machines. It runs on NixOS with flakes and Home Manager.

Start here

The guides

PageAbout
The panelevery page of the panel and the desktop plugin
Prompts and notificationsanswering prompts, Web Push, the channel, renaming
Sessionsstart, resume, resolve, kill, open, forget
Knowledgenotes, tools, injections, import and export
ReportsHTML reports: the skill, publishing, the viewer, storage
Machinesuptime and basic numbers, lock, suspend, wake-on-LAN
State sync~/.claude on every machine, the one-machine rule, conflicts
Workspace syncthe workspace root on every machine
Configurationevery key, and the module options
Architecturecomponents, protocol, the Claude Code interfaces used
Datawhat is stored where, retention, backups
Securitytokens, devices, what can reach the hub
Developmentbuilding, testing, the demo, the screenshots

The source and issues are on GitHub; the license is EUPL-1.2.

Installation

ccdash runs on NixOS with flakes and Home Manager: a hub keeps the state and serves the panel, a collector on every workstation reports its Claude Code sessions. Both can be one machine.

  1. Before you start
  2. The flake input
  3. One machine
  4. A hub and workstations
  5. Tokens
  6. Your phone
  7. Optional features
  8. Updating

1. Before you start

  • NixOS with flakes, and Home Manager (as a NixOS module or standalone) with programs.claude-code enabled.

  • Claude Code 2.1.157 or later as programs.claude-code.package, so every session gets the ccdash plugin (the knowledge tools and skills). A Home Manager without programs.claude-code.plugins builds with a warning, and only sessions with the channel get them.

  • To look around first: nix run github:tsandrini/ccdash#demo serves the panel on a made-up workspace at http://127.0.0.1:7840/#token=demo.

  • ccdash builds from source (a Rust daemon and a Svelte panel, a few minutes). A hub on a Raspberry Pi is better built on a faster machine: the flake has a cross-compiled ccdash-aarch64-linux.

    services.ccdash-hub = {
      package = inputs.ccdash.packages.x86_64-linux.ccdash-aarch64-linux;
      webPackage = inputs.ccdash.packages.x86_64-linux.ccdash-web; # static files
    };
    

2. The flake input

inputs.ccdash = {
  url = "github:tsandrini/ccdash";
  inputs.nixpkgs.follows = "nixpkgs";
  inputs.home-manager.follows = "home-manager"; # only its tests use it
};

The hub’s module is inputs.ccdash.nixosModules.hub, the workstation’s inputs.ccdash.homeModules.default; inputs.ccdash.nixosModules.default allowlists the reply channel (section 7).

3. One machine

The hub and a workstation in one, for a laptop or a desktop you use alone:

# NixOS
imports = [ inputs.ccdash.nixosModules.hub ];
services.ccdash-hub = {
  enable = true;
  localCollector = { enable = true; user = "me"; };
  workspaces = [ "~/code" ]; # under the home of each machine's user
};

# Home Manager, user me
imports = [ inputs.ccdash.homeModules.default ];
services.ccdash = {
  enable = true;
  hub.local = true;
};

The hub generates its tokens once (/var/lib/ccdash-hub/ui-token and the local collector’s) and listens on 127.0.0.1:7837. To open the panel:

sudo -u ccdash ccdash url --hub --config /etc/ccdash/hub.toml

It prints a link that signs the browser in with a token of its own. The workspaces are the directories your projects live in; see getting started.

The collector starts with graphical-session.target. On a machine nobody logs in to graphically, start it with the user manager instead:

services.ccdash.systemdTarget = "default.target"; # Home Manager
users.users.me.linger = true; # NixOS: the user manager runs from boot

4. A hub and workstations

4.1 The hub

An always-on machine (a home server, a Pi) that every workstation and the phone reach, on your LAN or VPN:

imports = [ inputs.ccdash.nixosModules.hub ];
services.ccdash-hub = {
  enable = true;
  collectors = {
    desk = "/run/agenix/ccdash-collector-desk"; # host name → its token file
    laptop = "/run/agenix/ccdash-collector-laptop";
  };
  workspaces = [ "~/code/work" "~/code/personal" ];
  nginx = { enable = true; domain = "ccdash.example.org"; };
  backup.enable = true;
};
# TLS, listen addresses and access control of the vhost are yours:
services.nginx.virtualHosts."ccdash.example.org" = {
  enableACME = true;
  forceSSL = true;
};

~/… is a directory under each workstation’s own home, so the users and the homes may differ; an entry with no / or ~/ in front (work) is under each workstation’s workspace root, and an absolute path is that path everywhere (getting started).

Keep it off the public internet: see security.

4.2 Each workstation

imports = [ inputs.ccdash.homeModules.default ];
services.ccdash = {
  enable = true;
  hub.url = "wss://ccdash.example.org/collect";
  hub.tokenFile = "\${XDG_RUNTIME_DIR}/agenix/ccdash-collector-desk";
  # workspace.root = "/srv/src"; # where the hub's relative workspaces are here
};

The machine’s host name must be its key in the hub’s collectors (desk above). Every option: Home Manager module options, hub module options.

A workstation can also run Windows, with a script in the place of Home Manager: a Windows workstation.

5. Tokens

  • The bootstrap token of the panel: leave tokenFile unset and the hub generates one; devices then pair with links of their own (section 6).
  • One collector token per workstation: any secret string, the same on both ends. Make one with openssl rand -hex 32.
  • The hub’s copy must be readable by the ccdash user, the workstation’s by you. Any secrets tool works: agenix (owner = "ccdash" on the hub, the Home Manager module on the workstation), sops-nix, or plain files with mode 0400.
  • One machine (section 3) needs none of this: localCollector generates its collector’s token.

6. Your phone

The panel is a web app, installable from the browser’s menu. The phone needs to reach the hub (a VPN, or nginx on your LAN), and Web Push needs HTTPS. On the hub:

sudo -u ccdash ccdash url --hub --config /etc/ccdash/hub.toml --qr

Scan the code: the link pairs the phone with a token of its own (good for an hour). Then Settings › Devices turns push on. More: prompts and notifications.

7. Optional features

Everything beyond reporting and answering is off until you turn it on.

FeatureTurn onMore
Replies from the panel (the channel)HM claudeCode.channel.enable, NixOS programs.ccdash.channel.allowprompts
Open a background session, edit a prompt in your editorHM terminal ({ command = [ "ghostty" "-e" ]; appId = …; }) and editorsessions
Sessions and prompt history on every machineHM sync.enablestate sync
The workspace root on every machinehub workspace.enable, HM workspace.enable and workspace.rootworkspace sync
Lock and suspend from the panelHM power.lock, power.suspendmachines
Model, context, cost and limits per sessionHM claudeCode.statusLine.enablepanel
Tokens, cache hits, commits in AnalyticsHM claudeCode.telemetry.enablepanel
The DankMaterialShell bar pill and dash tabHM dms.enablepanel
A nightly database copyhub backup.enabledata

The panel shows only what the machines do: without the syncs there is no Workspace or Claude state page, without a terminal no Open button.

8. Updating

nix flake update ccdash

Then rebuild the hub and every workstation together. Hub and collectors speak a versioned protocol; a collector older or newer than its hub is refused (refused: the hub speaks protocol 17, not 16 in its log) until both run the same release.

A Windows workstation

A Windows machine can be a workstation: the collector, the hooks, the CLI, the plugin and the channel run there and report to a hub on Linux. The hub runs on Linux only, as do ccdash demo (a hub), the DankMaterialShell plugin and niri.

Windows is kept working by the people who run it. ccdash is developed and used on NixOS; a CI job builds and tests the Windows side on every change, and a new feature may reach Windows later than Linux.

  1. Install
  2. Optional features
  3. Start at logon
  4. The hub’s side
  5. Updating
  6. Where things are
  7. Differences

1. Install

You need Rust with a C compiler (ring and the bundled SQLite need one: the MSVC toolchain, or the GNU one with MinGW), PowerShell 7, Claude Code 2.1.157 or later, and a collector token the hub lists under this machine’s host name (section 4). From the repository, as yourself (no elevation):

pwsh -File windows\install.ps1 -Build -Hub wss://ccdash.example.org/collect -Token .\token

It builds ccdash and installs:

  • ccdash.exe in ~\.local\bin, which joins your PATH;
  • the ccdash plugin in ~\.local\share\ccdash\claude-plugin, linked into ~\.claude\skills\ccdash: every session gets the knowledge tools and the ccdash:wrap-up, ccdash:report and ccdash:project skills;
  • the collector’s configuration, %APPDATA%\ccdash\config.toml, and its token, readable by you alone;
  • the hooks in ~\.claude\settings.json, next to any of your own (the file as it was stays as settings.json.before-ccdash);
  • the collector, started now and at every logon (section 3).

The host name is the DNS host name, lowercased; -HostName sets another.

A machine without a toolchain installs from a bundle: -Pack D:\bundle on one that has it writes the binary, the plugin, the wrapper and the script, but no token. Copy it over and run pwsh -File .\install.ps1 -Hub … -Token … there.

2. Optional features

As on NixOS, everything beyond reporting and answering prompts is off until you turn it on. A switch adds what it needs where it is missing, at the first install or any later run; what config.toml already says is kept.

FeatureSwitchSets
Replies from the panel (the channel)-Channel[launch] channel; the claude wrapper in your profile
Open a background session-Terminal[attach] command: claude attach {id}
Edit a prompt in your editor-Editor nvim[edit] command: nvim {file}
Sessions and prompt history on every machine-Sync[sync] enable
Workspaces under a directory of this machine-Root D:\src[workspace] root: where the hub’s relative workspaces are here (the hub’s side)
Model, context, cost and limits per session-StatusLineccdash tee as Claude Code’s statusline, in front of yours
Tokens, cache hits, commits in Analytics-Telemetry[telemetry] listen; the OTEL_* variables in Claude’s env
Lock and suspend from the panel—[power] lock, suspend in config.toml
Dictation, the words of attached recordings—[transcribe] command in config.toml (attachments)
Still frames of attached videos—[video] ffmpeg in config.toml (attachments)

To turn one off, edit config.toml (the channel: also the profile’s line) and run the script again. Every key: configuration.

The terminal. Windows has no terminal command to set: ccdash starts claude attach and the editor in a console of their own, and Windows shows it in its default terminal application (Settings › System › For developers › Terminal), Windows Terminal or the console host. The editor must be a console program that returns when the file is closed: exit status 0 takes the text, anything else (:cq) cancels.

The channel. The wrapper starts interactive sessions with --channels plugin:ccdash@inline, and sessions started from the panel get it through [launch] channel. Claude Code loads it only from its allowlist, allowedChannelPlugins in its managed settings (an organization’s server-managed settings outrank the machine’s), as the NixOS module’s programs.ccdash.channel.allow does. Without it, $env:CCDASH_CHANNEL_FLAG = '--dangerously-load-development-channels' loads the channel in the wrapper’s sessions, with a warning at every start.

3. Start at logon

The script adds ccdash collector --background to the Run key, which needs no elevation (a scheduled task, schtasks /SC ONLOGON, would). --background starts the collector again with no console window and returns; a window opened for the start alone, the Run key’s, closes at once. Two starts at once leave one collector.

Its log, rewritten at each start, is %LOCALAPPDATA%\ccdash\state\collector.log. Programs the collector runs share its hidden console; an editor and an attach open a window of their own.

From a script, start it with Start-Process, not by capturing its output: a pipe it inherited stays open while the collector runs.

4. The hub’s side

A collector token under the machine’s host name (installation). The workspaces need nothing written for Windows when they are under the home or the root:

services.ccdash-hub = {
  collectors.winbox = "/run/agenix/ccdash-collector-winbox";
  workspaces = [ "~/code/work" "clients" ];
};

~/code/work is C:\Users\me\code\work here and /home/me/code/work on a Linux machine; clients is under each machine’s workspace root, here what -Root set (D:\src\clients). Both are one workspace on every machine, and a session started or resumed from the panel goes to the machine’s own directory. A path of its own (''D:\work'') names the workspace work on the machines that have that path (getting started).

5. Updating

pwsh -File windows\install.ps1 -Build                  # binary, plugin, wrapper
pwsh -File windows\install.ps1 -Build -Pack D:\bundle  # for a machine with no toolchain

Running sessions keep the old binary, which is renamed aside rather than overwritten, and their channel reconnects to the new collector. The hub and its collectors must speak the same protocol: update the hub with them (installation).

6. Where things are

WhatWhere
config%APPDATA%\ccdash\config.toml
state%LOCALAPPDATA%\ccdash\state (outbox, sync index, notes cache, fetched attachments, the log)
runtime%LOCALAPPDATA%\ccdash\run (pending titles)
socketsnamed pipes \\.\pipe\ccdash-api-<hash>, \\.\pipe\ccdash-ingest-<hash>
binary~\.local\bin\ccdash.exe; ~\.local\share\ccdash\REV names its commit
plugin~\.local\share\ccdash\claude-plugin, linked as ~\.claude\skills\ccdash
Claude Code%USERPROFILE%\.claude, or CLAUDE_CONFIG_DIR

The pipes’ names hash the socket path under the runtime directory, so CCDASH_RUNTIME_DIR still gives a second collector a place of its own. They let in the current user only, and no remote client. The state and runtime folders get a DACL of their own for the user alone, which what they hold inherits, as mode 0700 does on Linux. XDG_* variables still win over the folders above, but for XDG_RUNTIME_DIR: the pipes are named after the runtime folder, which the collector and every hook must agree on, and only LOCALAPPDATA is the same for all of them. The collector’s log names its pipes.

7. Differences

AreaOn Windows
the hub, the demorefused: they run on Linux only
stop a sessionClaude Code’s tree ends at once (TerminateProcess), no SessionEnd hook; its console is then reset
interruptthe running Bash call’s process tree is ended at once
openno window focus; a background session is attached in a console of its own
editorin a console of its own; Windows Terminal keeps the tab open after a non-zero exit (:cq)
machineno load average (reads 0) or CPU temperature; wake-on-LAN: the card is armed (powercfg, 10 min)
lock, suspendLockWorkStation; SetSuspendState from a hidden PowerShell (sleep, not hibernation)
state syncReadDirectoryChangesW instead of inotify
workspace syncone recursive watch on the root; no open-file check for quiescence; git dirs outside a unit unwatched
network sharesnot watched (no extended change records): a root on one is swept every 30 min
npm’s claude.cmdruns, through cmd.exe; a batch file takes no multi-line argument, so such prompts need claude.exe

A session’s transcripts live under its directory’s name (C--Users-me-code-x), which no Linux machine has. Claude Code finds a session by its id whatever that name is, so a Windows session should resume on Linux and the other way round as between two Linux machines whose paths differ (state sync); between Windows and Linux nobody has tried it yet.

Getting started

What to do once the hub and a collector run (installation).

  1. A first session
  2. Workspaces and projects
  3. The knowledge tools and skills
  4. Bringing in what you have
  5. From the phone
  6. Settings worth a look

1. A first session

Start claude in a project as you always do. It shows up on Now and under Sessions within a second: working, waiting on a permission prompt, your turn, or parked when you have not answered for a while. Its page has the conversation, the shell output, the files it touched and its cost (with claudeCode.statusLine.enable). A permission prompt can be answered in the terminal or in the panel, whichever comes first.

On a workstation, ccdash status lists the machine’s sessions as the hub sees them; ccdash url prints the panel’s address.

2. Workspaces and projects

A workspace is a directory you listed in the hub’s workspaces; it is named by its last component. A project is a directory directly under it, a repository clone as a rule. An entry is written one of three ways:

EntryThe directory on a machine
~/codeunder its user’s home: /home/me/code, C:\Users\me\code
work, clients/acmeunder its workspace root: services.ccdash.workspace.root, [workspace] root
/srv/code, C:\codethat path, on every machine that has it

So ~/code is the workspace code on every machine, whatever its user is called, and /home/me/code/shop is its project shop there. A machine with no root has no directory of a relative entry, and no home is needed for a path of its own.

  • Memories, issues, progress, documents and reports belong to a workspace, and to a project of it or to the whole workspace. Every session of the workspace shares them, on every machine.
  • A session takes its project from the directory it runs in. At the workspace root, name it: /ccdash:project shop in the session, or claude --project shop to start one (the channel’s claude wrapper takes the flag).
  • A session outside every workspace still shows in the panel, but the knowledge tools refuse it, and the Now page warns while the hub has no workspace at all.
  • The machines’ paths may differ: each tells the hub where its home and its root are, and a session’s workspace is found in its own machine’s directory. Started or resumed from the panel on another machine, a session runs in that machine’s directory of the same workspace (sessions).

3. The knowledge tools and skills

Every session gets the ccdash plugin (claudeCode.plugin.enable, on by default):

ToolsFor
recallsearch the notes, or read one in full
remember, verifykeep a fact, confirm one still holds
issue_add, issue_updateopen work, with a status and a priority
progressa dated entry: what landed, what was decided
doc_writeplans, specs, anything long
report_publishan HTML report, kept on the hub
claim, releasetell the other sessions what this one works on
tell_sessiona message to another running session
SkillDoes
/ccdash:wrap-uprecords what the session learned and did, then lets it close (Resolved)
/ccdash:reportwrites a report in the shared design and publishes it
/ccdash:projectplaces the session under a project

At its start a session is told the project’s open issues, memories and recent progress (knowledge). Claude uses the tools more when your CLAUDE.md asks it to, for instance:

## Knowledge

Durable knowledge lives in ccdash: `recall` before asking about past
decisions, `remember` facts worth keeping, `issue_add` for work we agree on,
`progress` when something lands.

4. Bringing in what you have

ccdash import memory reads a workspace’s .claude/memory directory (one note per file, titled by its MEMORY.md line) and sends it to the hub through this machine’s collector; it is safe to repeat:

ccdash import memory ~/code/.claude/memory

Notes kept elsewhere, such as Claude Code’s own memory directory, go into the workspace’s .claude/memory first. Plans come in with ccdash import plan, and ccdash export writes every note back out as markdown (knowledge).

5. From the phone

Pair it (installation) and leave Now open: prompts are answered inline or from the notification’s buttons, a quick reply or a note for the next prompt goes to a session on your turn, and Start a session launches one in the background on a machine you pick. A notification waits 15 s, so a prompt answered at the desk never sends one (prompts and notifications).

6. Settings worth a look

  • Settings › Devices: the paired devices, push on this one, a test.
  • Settings › Composer: vim keys (off by default), line numbers, quick replies and templates, per device.
  • Settings › Appearance: the size of the panel on this device (smaller by default on a phone), light, dark or the system’s, and the colour schemes.

Troubleshooting

Where to look: the collector’s log with journalctl --user -u ccdash on the workstation (on Windows %LOCALAPPDATA%\ccdash\state\collector.log), the hub’s with journalctl -u ccdash-hub on the hub, and ccdash status for what the hub knows of this machine.

  1. A machine does not show up
  2. The knowledge tools refuse
  3. A session has no ccdash tools or skills
  4. A button is missing
  5. No notifications
  6. The panel asks for a token

1. A machine does not show up

Read the collector’s log; the first line about the hub says why.

The collector saysBecause
connecting: HTTP error: 401 Unauthorizedthe token is not one the hub lists: another secret, the wrong file, or the hub not rebuilt since
refused: this token is desk's, but the machine calls itself laptopthe host name differs from its key in the hub’s collectors: rename the key or set the collector’s settings.host
refused: the hub speaks protocol 17, not 16the hub and this collector are different releases: update both (installation)
connecting: … Connection refusedthe hub is down, or hub.url points elsewhere (/collect on the hub’s address, wss:// behind nginx)

Nothing in the log at all: systemctl --user status ccdash. The collector starts with graphical-session.target; a machine without a graphical session needs services.ccdash.systemdTarget = "default.target" and lingering (installation).

While the hub is unreachable the collector queues what happens and sends it once the link is back; nothing is lost.

2. The knowledge tools refuse

… is outside every ccdash workspace: the session runs in a directory under none of the hub’s workspaces. With the hub has none yet the list is empty; set services.ccdash-hub.workspaces. Otherwise start the session inside a workspace as this machine has it: the hub’s log names each machine’s directories when its collector connects (workspaces of desk: work in /home/me/code/work). A relative workspace needs the machine’s workspace.root (getting started).

3. A session has no ccdash tools or skills

  • claude plugin list should show ccdash@skills-dir.
  • The plugin needs claudeCode.plugin.enable (the default), Claude Code 2.1.157 or later, and a Home Manager with programs.claude-code.plugins; without that option the build warns and only channel sessions get it.
  • A session started before the switch keeps what it had: start a new one, or claude --resume it.

4. A button is missing

The panel offers only what the machine does.

MissingTurn on
Reply, Resolvedthe channel: claudeCode.channel.enable and programs.ccdash.channel.allow; restart the session
Open, Edit in the editorservices.ccdash.terminal and editor
Start a session (no machine)a connected collector with Claude Code (launch.command)
Lock, Suspendpower.lock, power.suspend
The Claude state, Workspace pagessync.enable; the hub’s and the collectors’ workspace.enable

On Windows the script’s switches turn these on (Windows).

Without the allowlist Claude Code does not load the channel, so Reply stays away; claudeCode.channel.devFlag loads it anyway, at the price of a warning dialog at every start.

5. No notifications

  • Web Push needs the panel over HTTPS (or localhost), and push turned on for the device in Settings › Devices; Send a test there checks it.
  • A notification waits 15 s, so a prompt answered in the meantime sends none.
  • What notifies is set on the hub (notify.* in the configuration).

6. The panel asks for a token

Open the link sudo -u ccdash ccdash url --hub --config /etc/ccdash/hub.toml prints on the hub (installation): it signs the browser in with a token of its own. A device signed out after the bootstrap token changed pairs again the same way.

The panel

The web panel (web/, SvelteKit) is served by the hub at / and is built phone first. Every view can be narrowed to workspaces and hosts: the scope is kept per device (browser storage), across pages and reloads, until you change it. The time range and the analytics section live in the URL, so links can be shared and the back button works.

  1. Now and Sessions
  2. A session’s page
  3. Projects
  4. History and Analytics
  5. Machines, Claude state and Workspace
  6. Themes
  7. Desktop (DankMaterialShell)

1. Now and Sessions

  • Now is the page to leave open on a second monitor; a look at it should replace opening the sessions. What needs you has the answer inline (permission prompts, questions, plans, sessions on your turn with a quick reply) and Resolved and Kill at hand. Every session that needs you or is working shows what you asked, what Claude last said, its last steps with the running one under them (failures in red with their error), tasks, subagents, the files of the turn and its numbers. A working session that has sent no hook for 10 minutes (30 while a tool runs) says “quiet” with how long: most likely a hung command or a dead process. The other open sessions follow in a line each. On wide screens a column beside them holds the limits, the system (machines and their link, open issues, the workspace sync, Claude’s state) and the last progress across projects by day, with the issue and the session of each entry; a phone stacks them. Start a session is here (sessions).
  • Sessions groups every session: those that need you, then working, parked and idle, then the ones Claude started (which show the session that started them and “Finished” instead of “Your turn”).
  • Sessions › Past is every earlier conversation the hub holds, from every machine: a search over what was said, filters for the machines (any number), project and time, cards with what you asked and where it ended, an overview and the conversation beside the list, and Resume… on the machine you pick (sessions). Resume… on Now opens it.
  • A session left on your turn for an hour is parked: most likely done, it no longer counts as needing you.
  • Every session card has an Actions menu: Open on, Resolved, Keep open, Resume, Kill, Forget, whichever apply (sessions).

Limits on Now

Each limit’s tile draws its current window behind the numbers: the readings so far, a dashed line to where the recent pace leads at the reset, and a faint diagonal for an even pace, so a line above it is running hot. Hovering reads the value off the line and a click opens Analytics › Limits. A window that reset with no reading since says so, rather than keeping the old number.

2. A session’s page

TabShows
Chatthe exchanges with Claude’s text, its steps, subagents, task notifications, subagent messages, messages between sessions
Shellits Bash calls as a terminal transcript with their output
Detailsthe project (pick one), the turn, files, tasks, processes, the claim, totals

Steps are the tool calls between Claude’s messages, written to be read at a glance: a run of them has one line (“Ran 9 commands, edited 2 files · 1 failed · 2m”) and its time range; each step is a sentence with an icon for what kind of thing it is: for a shell command, what Claude said it does (“Run the tests through the dev env”, the command dim below it; older calls, recorded before the description was kept, show the command), for files “Edited src/state.rs”, for searches the pattern, for a plugin tool its server and action with the argument that tells most (“playwright: click Units tab”). Consecutive reads, edits or searches of one kind fold into one row (“Read 4 files”, their names below). A failed step is red with the error’s first line. Tap a step for the command, its output and when it ran; the Shell tab has every command in full. The run of the exchange Claude is working on stays open, older ones are folded.

The block under the newest exchange shows what is happening now: the state, the running tool (what it does, the call below), the text Claude is writing, the turn’s tools and files, subagents and tasks, and a pending Stop (sessions).

Code blocks in replies, notes and the steps of a command have syntax colours in the theme’s palette, line numbers (kept out of a selection) and a copy button. A language the panel does not know, or a chunk it could not fetch, leaves the block plain.

Task notifications are what Claude Code tells a session when a background task reports: a subagent finished, a background command exited, a monitor saw an event, an MCP task completed. Subagent messages are a subagent’s report handed back, or a message it sends while it runs. Both reach the hooks as if you had typed them; the hub records them apart, so the chat shows them on Claude’s side in their own colour (what it is, the subagent’s or task’s name, the outcome, the report or event) and they never count as your prompts: not in the prompt history, the session’s last prompt, prompt counts or waits. A notification Claude Code appends to Claude’s text, when one arrives while Claude writes, is cut from it; Claude Code delivers it again on its own.

Open prompts are pinned above a composer that sends a turn through the channel or leaves a note for the next prompt; while Claude works, Stop interrupts the turn, so what you type next is what Claude reads (sessions). The composer is an editor made for long prompts: Enter is always a new line and only Ctrl Enter sends, on every device; it wraps, highlights markdown lightly, keeps an undo history that survives what the toolbar inserts, and Expand (Ctrl Shift F) gives it most of the screen. Vim keys are off until Settings › Composer turns them on (On, or Auto: on with a mouse, off on touch); it also holds a vimrc of maps they start with (jk leaves insert mode, Space w is :w); :w keeps the draft now, :x is done editing. Line numbers (none, absolute, or relative to the cursor’s line with the current one absolute, as Neovim’s number + relativenumber; Auto is relative with vim keys), the markdown highlighting and the wrapping are switches there too, kept per device. Two more go with vim keys, each a switch: the system clipboard is the unnamed register (yanks and deletes go to it; the browser’s paste keys, Ctrl Shift V and Shift Insert, paste as p does with no prompt anywhere, and a bare p reads the clipboard, which is a permission: Chromium asks once, Firefox puts a small Paste button under the cursor whenever the text came from another program, unless the helper below is installed; Settings can make p read the register instead), and hop: , in normal or visual mode, then two characters, labels every match in view with the keys you set (asdfghjkl, nearest match first, two-character labels when one does not suffice) while the rest of the text dims and a line under the text echoes what was typed; the label puts the cursor there, or in visual mode extends the selection through it; Escape or any other key cancels. When a message starts with / the composer offers the skills Claude Code loads for that session (the machine’s, the plugins’, the workspace’s), as the terminal does.

The field and its buttons are one frame, and the buttons are one row on every screen, so the chat keeps the height:

  • + adds to the prompt: a photo or a file (attachments; pasting a screenshot or dropping files on the field does the same), a template (Settings › Composer holds them), a [[note]] link, a skill, the text opened in your editor on a machine (below), and the panel’s keys.
  • The microphone dictates (Ctrl Shift D): it records, a machine puts the recording into words, and they land at the cursor to read over (dictation). It shows when a connected machine offers it; on a phone it takes Expand’s place in the row, and Expand moves into +.
  • Aa shows the formatting bar above the text: bold, italic, strikethrough, code, a code block, a link, lists, a quote, a heading, and Preview, which renders the markdown in place. Each button works on the selection and takes its mark away again when it is there. The bar stays as you left it on each device; it is off at first, since with vim keys or on a phone it is rarely worth its row.
  • Prompt history (Ctrl R) is a dialog over every prompt of the session and its workspace. The search takes several words in any order and asks the hub, so it reaches past the recent prompts; matches are set apart. Each prompt shows its session, its time and its length, a wide screen shows the picked one in full beside the list, a phone opens it in place. Enter or a tap uses it instead of the text (undo brings the draft back), Shift Enter inserts it at the cursor.
  • Expand (Ctrl Shift F), then the session’s own buttons: Stop while Claude works, Send, Next prompt.

? anywhere outside a field, or Keys and help at the end of the sidebar, lists every key:

KeysDoes
Ctrl EnterSend (Enter is a new line)
Ctrl Shift EnterNext prompt instead of a turn
Ctrl Shift 1–9That quick reply
Ctrl .Stop the turn
Ctrl GEdit in the editor on a machine (below)
Ctrl Shift FExpand the field, and back
Ctrl Shift DDictate; again to finish
Ctrl JGo to the open question
Ctrl ↑ Ctrl ↓Walk the prompt history
Ctrl RSearch the prompt history
Ctrl B Ctrl IBold, italic (with vim keys: in insert mode)
Ctrl ECode block around the selection
Ctrl PPreview
Esc, then iLeave the field (vim: normal mode), come back
?Every key, outside a field
Ctrl KSearch everything

The Firefox helper. Firefox lets only extensions read the clipboard without its Paste button (the clipboardRead permission is checked on the extension, never on a site), so firefox-ext/ holds one of a few lines: a content script on the panel’s origin that answers the page’s request for the clipboard. With it, p reads the clipboard at once, as in Neovim; without it the page falls back to the browser’s own read and its prompt. Settings › Composer says whether it is on the page. To use it: set matches in firefox-ext/manifest.json to your hub’s address, sign it (release Firefox installs signed extensions only; web-ext sign --channel unlisted with an AMO API key, from nix run nixpkgs#web-ext, gives an .xpi in a minute), then install the .xpi from the file, or through Home Manager with buildFirefoxXpiAddon from the NUR. The extension asks for nothing but reading the clipboard, and answers only the page it runs on.

Drafts live on the hub. What you type is kept there after a short pause (and on the device meanwhile), so a prompt begun on the phone is on the desktop, a reload or a closed tab loses nothing, and the start sheet opens with what you left in it. A draft is dropped when its prompt is sent, or after 90 days untouched.

Edit in the editor (Ctrl G, the terminal button) opens the draft in an editor on a machine, as Claude Code’s own Ctrl G opens the prompt in $EDITOR: the collector there writes the text to a file and runs its edit.command (off by default; the Home Manager module’s terminal and editor set it, such as ghostty -e nvim {file}, configuration); the field waits, with Cancel, until the editor closes, then takes the file’s content. Exit without saving (:cq) and the text stays as it was. Which machine: Settings › Composer names one; else the machine this device sits on, which the hub tells from the address (a connected collector linking from the same one; behind the module’s nginx the client address is passed on); else the session’s own machine; else the first connected one whose collector has the command. A machine without the command cannot be picked; one that disconnects while the editor is open frees the draft, and the text saved later still lands when its collector comes back.

The title renames in place; Open on and Resolved sit beside it, the other actions in its Actions menu, Resume at the foot once it ended (sessions).

3. Projects

Each workspace’s projects with their board (open issues), live sessions, progress, documents, memories and the note graph, and a reader and editor for every note (knowledge).

Search is one thing everywhere: the box on Projects and Ctrl K, from any page. It looks through every note’s title, summary and body by word prefix, ranked across workspaces (those in the scope), with the matching text shown. Narrow it by kind (or kind:issue in the text), order it by best match, newest or most recalled, and leave out retired notes, which otherwise come after the live ones. Ctrl K finds sessions and pages too (and offers to search the past sessions for the text), and a note opens beside the page you are on. Typing [[ in the composer searches the same way and inserts the link.

Graph is for exploring what the notes say about each other.

  • Search (/) is the same full-text search: matches stay bright and the rest dims, n steps through them, Only matches hides the others.
  • A click selects a note: it and its neighbours stay bright, and the panel beside the graph shows its links to walk along. A double click, or Open, reads it. With nothing selected, the panel has the numbers and the most linked notes.
  • Local graph (l) keeps only what is within 1 to 4 links of the note.
  • Path from here (p), then a click on another note, finds the shortest way between them.
  • The bar filters by kind, project, retired notes and notes without links; the slider goes back in time and plays the growth.
  • Display sets the colour (kind, project, age, links, recalls), the size, the layout (free, by project, along a timeline), which kinds of link count and the physics. It is remembered on the device.
  • 2D or 3D (d). 3D uses WebGL and is fetched the first time it is asked for; drag rotates, the wheel zooms, right drag pans. Layouts are 2D’s.
  • Full screen (f). Notes and the start sheet open on top of it.
  • 0 fits the view, Esc steps back: the path, the selection, the local graph, then full screen. Two fingers zoom on a phone.

In the graph, on any note, opens the graph with that note selected.

Work on this, on an open issue’s card and in the issue itself, opens the start sheet with its workspace and project picked and a prompt written, to edit. The session claims the issue as soon as it reports, so the card moves to In progress with the session on it.

Progress is a timeline, newest day first (with its entries, issues and sessions counted): each entry with its time, title and first lines, the issue it is on and whether that is open or closed now, the session that logged it (a link, with its host) and the project. All of it unfolds the whole entry in place.

4. History and Analytics

History draws the sessions of a time range as lanes coloured by state, with the totals, time per project, the most used tools and the 5-hour limit over time.

Analytics sections:

SectionAnswers
Overviewdaily activity, when you prompt (weekday × hour), work per prompt, cost, lines changed, CPU and memory per project
Waitshow long sessions waited on you and how fast you replied, apart from parked time
Parallelhow many sessions worked or waited at once; time everything waited with nothing working
Limits5-hour, 7-day and per-model weekly limits, their pace, each workspace’s share
Projectstime, prompts, cost, lines, tool calls, compactions and CPU per directory
Turnswhat fills a turn, the slowest tools and commands, the commands that fail most
Contextcompactions and how full sessions got
Tokenstokens by type, cache hits, API latency, commits, edits by language (needs telemetry)
Permissionswhat asks you most, grouped by the rule that would cover it, how you answered

A wait runs from Claude handing the turn back to what came next: a reply within an hour counts as waiting on you; a later reply, closing the session or leaving it open counts as parked; Claude carrying on by itself (a task notification, a wakeup) counts as neither. Permission prompts always count.

The time range in the top bar: quick ranges or an exact span, ‹ › to step, ⊖ to double it, and dragging across a time chart zooms in. Every chart has a tooltip and a table view.

The Tokens section and the approval sources under Permissions need Claude Code’s OpenTelemetry export: services.ccdash.claudeCode.telemetry.enable sets the OTEL_* variables and starts a receiver in the collector on 127.0.0.1:7839. It keeps counts and timings only; prompt text stays redacted, as Claude Code sends it by default.

5. Machines, Claude state and Workspace

The sidebar has three groups, a line between them: the work (Now, Sessions, Projects, Reports), what is kept and measured around it (Files, History, Analytics, Machines, Claude state, Workspace) and the panel’s own (Settings, Keys and help). Files lists what was attached to prompts and is still on the hub, with Keep and Delete (attachments).

Machines shows the hub’s own machine (uptime, CPU, temperature, memory, disks, system), then every node, that is every machine with a collector. A node’s card has how it is doing (up, CPU, temperature, memory, battery), its link and round trip, the sessions on it, its copy of Claude’s state, its share of the workspace sync, whether its screen is unlocked (with Lock), and Wake while it is down. A node’s page starts with the machine itself:

  • tiles for uptime (with the time slept and the last resume), CPU, memory, each disk and the battery
  • the OS, the kernel and whether a reboot is pending
  • its power: Lock, Suspend, Wake, Forget (machines and power)

Then it gathers what the other areas know about the node:

  • the sessions on it now
  • Claude’s usage there over the range in the bar (sessions, working time, cost, lines, CPU, activity by state)
  • its copy of Claude’s state
  • its workspace sync (units in step, what moved and what it cost in the range, the units not in step there, its large transfers)

Host names on the Now page and in the Workspace area open it.

Claude state is each machine’s copy of ~/.claude (the state sync): machines with Resync, conflicts with their resolutions, sizes and growth.

Claude state and Workspace are in the sidebar only while their sync is on (a collector with sync.enable, a hub with workspace.enable); so are their lines on the Now and Machines pages. Each collector tells the hub what it does, so Open, Edit, Start and Resolved show only on machines that can.

Workspace is the workspace root on every machine (the workspace sync), in sections: Overview (the tiles, what needs you with the buttons at hand, the machines in a line each, the last day’s traffic, the units that changed last), Units (a sortable table with a search, state filters and a chip per machine, new directories, held snapshots, conflicts; a unit’s page with its state on every machine, diverged branches, conflicts, the ignored directories with a switch each, overrides and the snapshot history), Machines (a card per collector: the link’s round trip, what it moved today and this week, the rate of its large transfers, what the sync cost in CPU, I/O and memory), Statistics (the range in the bar, a year back: traffic, pushes, CPU and memory per machine, the hub’s repositories, conflicts) and Configuration (the rules with live match counts and what each never- travelling name keeps home, previewed by the hub as you type; then the coverage: what travels and what stays home on every machine, and why).

6. Themes

Settings › Appearance › Size sets how big the panel is on this device: text, buttons and spacing change together, in five steps from Smallest (80 %) to Largest (125 %). Auto, the default, is Small (87.5 %) on a phone and Normal on a tablet or a computer: a phone’s own apps set their text a size under a web page’s, and at Normal the panel’s bars take the room the chat needs. A zoom set in the browser, or in an installed app’s site settings, applies on top; set it back to 100 % before judging the sizes.

The theme menu in the top bar and Settings › Colours pick the mode (system, light, dark) and the colour scheme, per device: Neutral, ccdash, Catppuccin, Gruvbox, Nord, Tokyo Night, Rosé Pine, Everforest, Kanagawa, Solarized, Dracula (dark only), or Wallpaper.

Wallpaper follows a machine’s desktop colours, as they change. The collector reads them from the files the desktop already generates, on every machine that has one, and reports them to the hub, so the phone can follow them too:

Read firstOtherwise
DankMaterialShell/dms-colors.jsonwal/colors.json

Both under $XDG_CACHE_HOME (~/.cache).

DankMaterialShell’s has both modes and Material’s colour roles; pywal’s has one mode, which then decides light or dark. The newer file wins, so running wal on a machine that used to run DankMaterialShell takes effect. pywalfox needs nothing here: it shows the same wal/colors.json in Firefox, and a page cannot read an extension. With several machines reporting, Settings › Colours picks which one to follow; a machine that stops reporting leaves its last colours in place.

A palette names colours, not meanings: pywal fills its slots in any order. So the panel takes each state’s hue from the nearest colour the wallpaper has, makes one at the wallpaper’s strength when it has none, and moves lightness until text reads against the background (web/src/lib/theme.ts).

7. Desktop (DankMaterialShell)

services.ccdash.dms.enable = true links the plugin into DankMaterialShell: a bar pill with the sessions that need you, a dash tab and card, notifications when a session starts waiting, and dms ipc call ccdash focusWaiting to jump to the session that has waited longest. Enable it once under Settings → Plugins and add the widget to a bar. niri binds:

Mod+C { spawn "dms" "ipc" "call" "dash" "toggle" "plugin_ccdash"; }
Mod+Shift+C { spawn "dms" "ipc" "call" "ccdash" "focusWaiting"; }

Clicking a session focuses its terminal window. The plugin opens the panel without a token, so pair the desktop browser once (security).

Prompts, notifications and replies

  1. Answering prompts
  2. Notifications (Web Push)
  3. Replying to a session
  4. Renaming

1. Answering prompts

Tool approvals, questions (AskUserQuestion) and plans (ExitPlanMode) show up in the panel while the terminal dialog stays open; whichever answer comes first wins.

PromptAnswers
Tool callAllow, Deny, Always allow (when Claude Code suggests a rule), Deny with a note
Questionone button per option (several for multi-select), or your own text
PlanApprove, Keep planning (with a note)

“Always allow” saves the rule where the terminal’s “don’t ask again” does, usually the project’s .claude/settings.local.json. Deny stops Claude like the terminal’s No; “Deny with a note” lets it carry on with your note.

How: the PermissionRequest hook is ccdash ask. It hands the prompt to the collector, which holds it until the hub answers or the prompt closes in the terminal (or the hub link drops: then the hook lets go and the terminal alone decides). Claude Code runs the hook alongside the dialog (verified on 2.1.302; the hooks reference promises this only for SDK hosts, so recheck after updates). services.ccdash.claudeCode.asks.enable = false makes the hook report prompts only.

2. Notifications (Web Push)

Served over HTTPS, the panel installs as an app and takes Web Push: Settings → “Turn on push notifications”, then “Send a test”.

  • A notification shows the prompt with as many buttons as the platform allows (two on Android); tapping it opens the session. A watch mirroring the phone can press the buttons too.
  • It waits 15 s (2 minutes while the session’s window has focus), so a prompt answered at the desk never sends one, and it closes once the prompt is answered anywhere.
  • A finished turn of a session started from the panel notifies “Finished”.
  • The hub generates its VAPID key pair on first start; messages are encrypted for the device (RFC 8291), so the push service sees only ciphertext. Devices the service reports gone are forgotten.
  • A button calls POST /act/<key>/<action> with a random key that belongs to that one prompt and dies with it; the access token never goes into a notification. The phone has to reach the hub (LAN or VPN).
  • Every notification has a kind: permission prompts, questions, plans, finished turns, and the workspace sync’s held snapshots, conflicts, new directories over the threshold and failing units. Settings › This device lists them as checkboxes under the push switch; a kind unticked there is not sent to that device (the others keep their own choice), and a kind the hub’s configuration turns off (notify.turns = false) never notifies. A device muted at the moment a notification is due does not get it later.
  • A push endpoint must be https; a loopback http endpoint (a push service on the hub’s own machine, for testing) is the one exception.
services.ccdash-hub.settings.push.subject = "mailto:you@example.org";
services.ccdash-hub.settings.notify = {
  turns = false;              # no "Finished"
  workspaces = [ "work" ];    # only these workspaces
};

3. Replying to a session

With the channel, a session’s page gets a message box. A message sent while Claude works waits for its next turn; Claude sees it as a <channel source="plugin:ccdash:ccdash"> event and the terminal shows ← ccdash: ….

# Home Manager: start interactive sessions with the channel
services.ccdash.claudeCode.channel.enable = true;
# NixOS: allow the plugin in Claude Code's managed settings
programs.ccdash.channel.allow = true;

The channel is for replies only: the knowledge tools and the skills reach every session through the plugin without it (knowledge). Without the channel, Resolved stays out of the panel and the message box leaves a note for the session’s next prompt.

This uses Claude Code channels, a research preview: ccdash channel is an MCP server every such session runs, connected to the collector.

  • Without the allowlist entry, claudeCode.channel.devFlag = true loads the channel with --dangerously-load-development-channels, and Claude Code asks for confirmation at every launch.
  • Claude Code’s startup notice lists plugin:ccdash@inline · plugin not installed: it only counts marketplace plugins; the channel works anyway.
  • Team and Enterprise accounts need an admin to enable channels.
  • Sessions started before (or without the wrapper) show how to restart them.
  • / at the start of the box lists the skills of the session’s machine and workspace, with their descriptions; the arrows and Enter, Tab or a tap pick one. Built-in commands (/compact, /clear, …) are not offered: a channel message reaches Claude as text, not Claude Code’s input line.

4. Renaming

Sessions can be renamed in the panel, the DMS plugin and with ccdash rename. The new name shows at once and reaches Claude Code at the session’s next prompt (or resume) through the sessionTitle output of ccdash’s hook, so the terminal title and Remote Control follow.

Sessions from the phone

What can be done to a session sits in its Actions menu, on every session card and on its page. Now pins Resolved and Kill on the sessions that need you, and the session page pins Open on and Resolved. An action that cannot run shows disabled, with why.

  1. Start
  2. Resume
  3. Resolve
  4. Interrupt
  5. Kill
  6. Open on the desktop, forget
  7. Background sessions
  8. Configuration

1. Start

Start a session on Now (or Start on a project page) asks for a connected host, a workspace and one of its projects, the model, the effort (the default, or low to max), the permission mode (the host’s default, plan, accept edits) and the prompt. The lists narrow as you type: the model’s has the aliases (opus follows the newest release) and the versions by name, and takes any other name claude --model knows. The panel waits until the session reports and opens its page; its prompts reach the phone like any other’s, and a finished turn notifies “Finished”.

The session starts in the workspace’s directory, whatever the project: that is where the harness (settings, rules, skills, the root CLAUDE.md) and direnv live. The project is the session’s label (see knowledge): the hub writes it onto the session when it reports, its notes default to it, and the project’s other sessions are the ones it hears about. The panel never sends a path, and the hub refuses unknown hosts, projects, models, modes and fields; the project list is the workspace’s projects that have notes and a directory on the chosen host. The collector then runs, in the workspace’s directory:

<launch.command> --bg [--resume <id>] [--model <m>] \
  [--permission-mode <pm>] [--effort <level>] --channels plugin:ccdash@inline \
  --settings $XDG_STATE_HOME/ccdash/launch/<launch id>.json -- <prompt>

claude --bg prints the session’s id, and the session’s hooks carry the launch id (CCDASH_LAUNCH in the settings file’s env: background sessions run under Claude Code’s supervisor, which never sees the collector’s environment), so the hub finds the session either way. With launch.direnv set, the collector first runs it (direnv export json) in the directory and puts the variables matching the launch.env globs into the same env, so a launched session has what the workspace’s .envrc gives a terminal there; a direnv failure fails the launch. The file is owner-only and kept as long as Claude Code lists the job, whose saved options name it, and 30 days otherwise. --settings replaces an earlier one, so launch.command must not carry its own. Nothing else is passed: never --dangerously-skip-permissions.

A host has to trust the workspace first: --bg refuses a directory nobody accepted the trust prompt for, and the failure shows in the start sheet. Run claude once in the workspace’s directory on a new machine.

2. Resume

Any past session resumes on any connected machine that syncs: the collector fetches the transcript first, and starts the session in that machine’s own directory of the workspace, so the machines’ paths may differ. An ended session’s page has Resume… at its foot (and in its Actions menu); every other one is found under Sessions › Past.

Resumed as it was, a background session of the same machine goes on under its own id. Pick another model, effort or permission mode and Claude Code continues it as a copy under a new id, on those; the old one stays. A session whose transcript two directories hold (a copy made by hand) is found by neither: it is continued from the newer one, as a copy.

A copy is the same conversation under another id, and the panel shows it as one. The copy takes the title over, and its chat starts with the earlier session’s part: a line marks where it went on, with the model and effort on either side when they changed (Opus 5.5 → Fable 5.2) and a link to the earlier session. Its header and card say what it continues; the earlier session’s say what it was continued as, and its page offers Open the copy. An ended session leaves the Ended list to its copy, and Past marks it continued. Cost, context, the process and Kill stay each session’s own, and a session that was copied while it ran goes on by itself: the copy’s chat shows it up to the moment of the copy.

A running session takes no other model or effort from outside, only /model and /effort typed into it. For a background session the panel does the next best thing in one step: Switch model & effort… in its Actions menu asks for the two and the next prompt, says what it is about to do, and on Stop and switch the hub stops the session (claude stop) and continues its conversation as a copy on what you picked. A turn in progress is cut off. If the stop fails nothing changes; if the copy fails to start, the session stays stopped and the same sheet (or Resume… on its page) starts it. A session in a terminal is not offered this: change it there.

Finding it: Sessions › Past

Past (/sessions/past, also Resume… on Now and “Search past sessions for …” in Ctrl K) lists every conversation the hub holds: the transcripts of every machine that syncs, the ones from before ccdash too, newest first and grouped by day.

  • Search looks through what was said: your prompts, Claude’s replies and the titles, by word prefix, diacritics ignored; "…" for a phrase. Sessions with every word come first; when none has them all, the ones with some (the line above the list says so). Each card shows where it matched, who said it and when.
  • Machines (any number; all by default, the bar’s host when one is picked): sessions any of them wrote to. Project, When (24 hours to a year) and Sort (best match, last active, started, most prompts, largest, most expensive) sit beside it, each with its counts. Filters and the open session are in the address, so back and links work.
  • A card has the machine it last ran on (and how many others), the workspace and project, the branch, when it was last active, the title, what you asked first and where it ended (Claude Code’s recap when it wrote one, else Claude’s last words), the prompts, the time Claude worked, the transcript’s size, the cost and the model; marks for running, continued (resumed later as a copy), headless (claude -p, the SDK) and outside workspaces.
  • A session opens beside the list (its own view on a phone): every machine it ran on (online or not), the directory and branch, Resume…, its page when the hub has its chat, and the terminal command (cd <dir> && claude --resume <id>) to copy. Overview has the recap, what you asked first, where it ended (your last prompt and Claude’s last reply), the matches of the search, every prompt (a click reads from there), the files it edited, dates, size, cost, models and the Claude Code version. Conversation has your prompts and Claude’s text in order, tool calls left out, paged.
  • Keys: / search, ↑ ↓ (or j k) move, Enter resume, Esc close.

The hub reads the transcripts into its catalog as the sync brings them; on the first start that takes a minute or so, and the page says how many are left. A session started from a machine without the state sync is not there: its page (from Sessions) still resumes it on its own machine.

What runs

Resume… opens the start sheet: pick the machine (the connected ones with the session’s workspace; the one it last ran on is marked, an offline one shows why it cannot be picked), the model, the mode and the prompt.

Where, howWhat runsSession
its job is on that machine, nothing changedclaude --bg --resume <id> -- <prompt>the same one, same options
another machine, another model or mode, or its settings file is gonethe command of Starta copy under a new id

Claude Code keeps a job’s options itself: with any flag it starts a copy instead, so a job of that machine runs with none, launch.command’s included. Those options name the launch’s settings file, and without it the job fails to restart, so ccdash notes which job a file belongs to and takes the copy when it cannot tell. The page follows a copy. A session that ran outside every workspace, or runs now, cannot be resumed from the panel: the first resumes in a terminal (the copied command), the second is open already.

3. Resolve

Resolved (it asks first) ends a session whose task is done, after one last turn of cleanup. The hub sends this prompt through the channel:

Task is resolved, user is closing the session.

Wrap up with the ccdash:wrap-up skill: record what this session learned and did
in ccdash (memories, issues, progress) and release its claim. Ask nothing and
start no new work: the session closes when this turn ends.

The wrap-up skill ships with the ccdash plugin: Claude closes or comments the issues it worked on, logs progress, records durable memories, releases its claim and ends with a short summary, which stays on the session’s page. It edits, commits and pushes nothing.

When the turn that prompt starts ends, the hub closes the session as Kill does; until then the card reads “Resolved”. Resolving a session that is working queues the prompt after its current turn.

Happens before the closeThen
Keep open (Actions), or you type onthe mark goes; the session stays after its wrap-up
the wrap-up turn fails (an API error)the mark goes; the session waits on you
closing fails (the process won’t exit)your turn, with why
the hub restartsthe mark comes back from the stored events

Resolve needs the ccdash channel; without it the action shows disabled. A sleeping session has none: send it a message first, or Kill it.

4. Interrupt

Stop in a working session’s composer, or Interrupt in its Actions menu, ends the current turn the way Esc does in the terminal: Claude stops, the session is on your turn, and what you send next is what it reads. No confirmation: nothing is lost but the rest of the turn.

How it lands, through the hooks only (Claude Code’s documented way; a SIGINT would exit the process):

The session isWhat happens
waiting on a permission promptthe prompt is denied with Claude Code’s stop; the turn ends at once
about to call a toolthe PreToolUse hook denies the call and ends the turn (continue: false)
running a Bash commandthe command is ended, as Esc does; Claude is told why and ends the turn in a line
running another toolit runs to its end; the PostToolUse hook then ends the turn
writing text, no tool call aheadthe turn ends by itself; the interrupt is dropped with it
run by hooks older than ccdashthe action shows disabled: interrupt it in its terminal

A running command gets SIGTERM with its whole process group, and SIGKILL 3 s later if it ignores that. A shell left running in the background by an earlier call stays, as do MCP servers. Claude Code takes no stop from a hook after a failed tool call, and an ended command is one: the hook tells Claude that you stopped the turn, Claude ends it in a line, and a tool call it tries anyway is denied.

It is not Esc: nothing reaches Claude while it thinks or writes, so the stop lands at its next step, and a long reply runs to its end. Kill ends a background session at once and keeps its conversation.

Until it lands the live block reads “Interrupting: Claude stops at its next step”; then the chat shows Interrupted from ccdash where the turn ended. The terminal shows “hook stopped continuation: Interrupted from ccdash: the user stopped this turn from their dashboard”, and Claude reads the same line at its next turn, so it knows why it stopped. Claude Code fires no Stop hook for an interrupted turn; the hub closes the turn on the hook’s report. A subagent’s tool calls do not take the interrupt: the main thread’s next step does.

5. Kill

Kill asks first and answers only once the session is over. Never SIGKILL.

SessionWhat Kill does
InteractiveSIGTERM to its Claude process (only one that is still Claude Code); after 5 s, SIGTERM to its child processes too; if it still runs, Kill says what it waits for
Backgroundclaude stop <id>; when that fails and no process runs the session, claude rm <id> (keeps the conversation)

Why the escalation: Claude Code acts on SIGTERM only once an editor it opened for the prompt (Ctrl+G), or a running command, has finished.

A killed session stays ended: Claude Code goes on listing its job as done, and a listed job only keeps an open session open. Resume brings it back.

6. Open on the desktop, forget

  • Open on (the host’s name) focuses the session’s terminal window, or attaches a background session in a new terminal (attach.command), as ccdash open does.
  • Forget, when the session’s host is offline, marks it ended on the hub; it comes back if its host reports it running again.

7. Background sessions

A session you started, from the panel or with claude --bg in a terminal, is yours like any other: it shows in Working, Needs you and Parked, and a finished turn notifies. Background agents are only the sessions Claude started; they report to the session that started them, and end with their job.

At each turn’s end Claude Code labels the job from Claude’s closing words (claude agents --json). Both labels mean a turn ended and the session waits for you, so ccdash treats them alike:

stateClaude Code meansccdash shows
workinga turn is runningWorking
blockedit needs something from youyour turn, then parked
donefinished what you asked, ready for the next promptyour turn, then parked
failed, stoppedit endedended, with Resume

Asleep. After about an hour unattached (8 h with Remote Control, a minute when memory runs low) Claude Code stops an idle session’s process and keeps its job. The session stays open, marked asleep, and the composer stays: a message runs claude --bg --resume <id>, the session comes back on its saved options, channel included, and reads the message as its prompt (or as a copy, as with Resume; the old row then ends). If that fails, the session says why and your text stays on the page. An asleep done session stops showing as open after 7 days; Resume still brings it back. A job Claude Code no longer lists ends its session.

The supervisor that runs these sessions is its own user service (see Configuration), so a collector restart leaves them alone, and so does restarting the service: the next supervisor adopts them. A machine shutdown still stops them; they show as ended, and Resume brings the conversation back.

8. Configuration

The Home Manager module fills these in with the Claude Code binary and the ccdash plugin, so the channel, the knowledge tools and the skills load as in a terminal. It also runs claude daemon run as the user service claude-daemon (services.ccdash.claudeCode.daemon.enable): started on demand from the panel, the supervisor would live in the collector’s cgroup and die with it. The service starts with default.target, so a machine nobody logs in to needs loginctl enable-linger.

A session runs with the PATH of whatever dispatched it, so sessions from the panel get the collector’s, which keeps the user manager’s.

Open (attach to a background session) and Edit in the editor need a terminal; without one the panel leaves them out. The Home Manager module writes both commands from services.ccdash.terminal (and editor).

# collector config
[launch]
command = ["claude"]                  # + the arguments above; [] turns starting off; a job
                                      # continued on this machine runs without its arguments
channel = false                       # true adds --channels (Home Manager: claudeCode.channel.enable)
stop = ["claude", "stop", "{id}"]
remove = ["claude", "rm", "{id}"]     # when stop fails on a job nothing runs

[attach]
command = []    # off; e.g. ["ghostty", "-e", "claude", "attach", "{id}"]

[edit]
command = []    # off; e.g. ["ghostty", "-e", "nvim", "{file}"], the panel's Edit in the editor
                # ([panel](panel.md#2-a-sessions-page))

Attachments

A photo of a board taken at work, a screenshot of an error, a log, a PDF, a short video: the panel attaches files to a prompt, from the phone or the desk, and Claude opens them on the machine its session runs on. The microphone dictates a prompt instead of typing it.

  1. Attaching
  2. What Claude gets
  3. Photos are made smaller
  4. Files: what is kept, and for how long
  5. How it works
  6. Turning it off, and the bounds
  7. Dictation
  8. Recordings and videos
  9. Not yet

1. Attaching

In a session’s message field, and in the sheet that starts a session:

  • + › Photo or file picks one or several (ten at most per prompt);
  • + › Take a photo opens the camera, on a phone or a tablet;
  • paste a copied screenshot or file into the field (Ctrl V);
  • drop files on the field.

Each file shows above the buttons with its size while it uploads; the ✕ cancels an upload or takes the file out again (and off the hub). Send waits for the uploads. A prompt may be nothing but its files. Uploaded files of a prompt you have not sent yet survive a reload on that device.

In the chat a prompt’s pictures show as thumbnails that open large, recordings and videos get a player, anything else a chip to download.

2. What Claude gets

Claude Code takes text from the panel and nothing else, so the prompt names each file where Claude’s own tools find it:

What is on this board?

[Attached image: /home/you/.local/state/ccdash/attachments/3e2b…/board.jpg]
KindWhat Claude does with it
picture (JPEG, PNG, GIF, WebP)sees it, by reading the file
PDF, text, codereads it
sound, videocannot hear or watch: it gets the words and still frames (below)
anything elseopens it with whatever tool fits, if one does

The kind is read from the file’s first bytes, never from its name: an SVG or a page is text to ccdash, so it is never drawn in the panel.

When a file cannot be put on the session’s machine (the hub cannot be reached from there, the file’s time on the hub ran out), the prompt still goes out, with a line saying so in the file’s place; Claude tells you, and the chat marks the file.

3. Photos are made smaller

A phone photo is 12 megapixels and 4 to 8 MB; Claude scales every picture down to 2576 pixels on its long side (1568 on models before Claude 4.7) before it looks. So the panel does that first, in the browser: about half a megabyte goes over mobile data instead, nothing Claude would have seen is lost, and the photo’s place and device data stay behind.

Settings › Composer › Attachments turns this off or picks 1568 px; + › Photos in full size is the same switch. For fine print send the photo in full and ask Claude to crop: it can cut a region out of the original with its tools and read that. Screenshots that are small already go as they are, and a GIF keeps its frames.

4. Files: what is kept, and for how long

Files in the sidebar lists everything attached and still on the hub: the picture or the kind, the session it came from, the size, whether a machine ever fetched it, and when the hub drops it.

  • A file is dropped 30 days after its upload (retention_days).
  • All files together may take 5 GB (quota_mb); when the store is full, the oldest ones go first.
  • Keep pins a file past both; Delete takes it away now.

Dropping a file loses little: once Claude read a picture it is part of that conversation, on the session’s machine. A session’s machine keeps the files it fetched for 7 days after their last use ([attachments] keep_days in its collector’s configuration).

5. How it works

In order:

  • The panel uploads the file to the hub (POST /api/v1/attachments, the body streamed to disk under attachments.dir) and gets an id.
  • The prompt goes out with a marker per file, [ccdash-attachment <id>].
  • The collector of the session’s machine sees the marker when it delivers the prompt (through the channel, as a new session’s first prompt, or as a note with the next prompt), fetches the file with its machine’s token into ~/.local/state/ccdash/attachments/<id>/, and puts the line with that path in the marker’s place.
  • Claude reads the file. Reading outside a session’s own directory needs a permission: the Home Manager module adds the rule for that directory (services.ccdash.claudeCode.attachments.enable), and sessions started from the panel carry it in their settings.

A session that moves to another machine gets its later attachments there; the hub’s copy is the one that counts.

6. Turning it off, and the bounds

On the hub (services.ccdash-hub.attachments in the NixOS module, or [attachments] in its configuration):

KeyDefaultIs
enabletrueoff: no attaching in the panel, no Files area
dirattachments/ next to the databasewhere the files are
max_image_mb25the largest picture
max_audio_mb50the largest sound recording
max_video_mb300the largest video
max_file_mb50the largest file of another kind
quota_mb5120all files together; 0: no quota
retention_days30when an unkept file is dropped; 0: never by age

The NixOS module sizes nginx’s body limit for the upload from the largest of the four caps.

On a workstation (services.ccdash.settings.attachments, or [attachments] in the collector’s configuration):

KeyDefaultIs
enabletrueoff: this machine fetches nothing, the panel says so
dirattachments/ in ccdash’s state directorywhere fetched files go
keep_days7a fetched file unused this long is dropped; 0: kept

A machine fetches only when its collector has a token for the hub (hub.token_file).

7. Dictation

The microphone in a message field (Ctrl Shift D, or + › Dictate) records; Done sends the recording to a machine that puts it into words, and the words land at the cursor for you to read over, correct and send. Nothing is sent by itself. Cancel throws the recording away. A recording stops by itself after ten minutes, and it is not kept: the hub drops it once the words are back.

The words are made on a workstation, by whisper.cpp, on your own hardware: nothing goes to a service. One machine has to offer it:

services.ccdash.transcribe = {
  enable = true;
  language = "auto"; # or "cs", "en": steadier on short sentences
};

That fetches the small model (466 MB, many languages; a sentence takes a few seconds on a desktop’s processor) and sets [transcribe] command. transcribe.model takes another model file, transcribe.extraArgs more arguments for whisper-cli; without the module, set the command yourself: it gets the recording’s path as {file} and prints the words.

The panel asks the session’s own machine when it can, else any connected one that can; Settings › Composer › Dictation names one for good. The microphone needs the panel opened over https (or on localhost), and the browser asks once for it.

8. Recordings and videos

Claude cannot hear or watch, so the session’s machine makes something it can read, once, when the prompt is delivered:

  • of a video, still frames spread evenly from its start to its end (12 by default, at most 1568 pixels on the long side), with services.ccdash.video.enable (ffmpeg);
  • of a video or a sound recording, the words said in it, in a text file, with services.ccdash.transcribe.enable.

The prompt names both under the file’s own line, and Claude reads the frames it needs:

[Attached video, which you cannot watch: /…/attachments/3e2b…/clip.mp4]
[Frames of 3e2b…: 12 stills, one every 3.5 s from its start to its end, are in /…/3e2b…/derived/frames/ as 001.jpg to 012.jpg. Read the ones you need.]
[Transcript of 3e2b…: what is said in it is in /…/3e2b…/derived/transcript.txt]

The chat shows the video or the recording with a player and a line with what Claude got. When a machine has neither tool, or one fails, the prompt says that instead, so Claude does not guess at a file it cannot open. A long video takes a while to cut and to put into words: the prompt goes out when that is done, and the chat shows it as sent meanwhile.

KeyDefaultIs
transcribe.command[] (off)prints what is said in {file}
transcribe.timeout_secs300the command is stopped after this long
transcribe.attachmentstrueattached recordings and videos get their words too
video.ffmpeg"" (off)the ffmpeg to cut frames with (ffprobe beside it)
video.frames, .edge12, 1568how many frames, and their longest side in pixels
video.timeout_secs300cutting is stopped after this long

9. Not yet

  • Recording a voice message or a video inside the panel as an attachment: the phone’s own camera and recorder do it through Photo or file.
  • Attaching a file again from Files, and the phone’s Share sheet.

Knowledge: memories, issues, progress, documents

The hub holds what Claude should know across sessions and machines, as notes with [[slug]] links, backlinks and full-text search, each in one workspace.

  1. Notes
  2. Tools
  3. Injections
  4. Offline
  5. Lifecycle
  6. Import and export

1. Notes

KindFor
memoryfacts worth keeping
issueopen work, with a status
progressdated entries
docplans, specs, anything long
reportan HTML report’s abstract; the file is the hub’s (reports)

The Projects page shows every project’s notes, searches and edits them. Tick notes in its search results, across searches, and Export gives a .zip for someone without ccdash: markdown with frontmatter under <kind>/<slug>.md and an INDEX.md, so their Claude can read it like a memory directory. Links inside the selection stay [[slug]]; a link out of it becomes that note’s title.

2. Tools

Sessions reach the notes through tools of the ccdash plugin’s MCP server (ccdash channel), which the Home Manager module gives every session (claudeCode.plugin.enable, on by default; the channel is not needed): recall, remember, verify, issue_add, issue_update, progress, doc_write, report_publish (reports), and between sessions claim, release and tell_session. The plugin also carries the ccdash:wrap-up, ccdash:report and ccdash:project skills.

The tools need a workspace: a session outside every one the hub lists (services.ccdash-hub.workspaces, the TOML’s workspaces.dirs) is refused, and the Now page says so while the list is empty. Bring in what you had before with ccdash import (below).

  • Every call is scoped to the calling session’s workspace; a session never sees another workspace’s notes.
  • A note belongs to a project or to the whole workspace. The project is a label from a closed set: a directory directly under the workspace on some host, or one that already has notes; anything else is refused. A call names it with project, else the note takes the session’s. An empty project on remember or issue_update makes a note workspace-wide.
  • A session’s project is the launch’s (the panel), or claude --project <name> in a terminal (which sets CCDASH_PROJECT; the channel wrapper takes the flag), else the one it claims with project, /ccdash:project <name> asks for, or the owner picks on its page (Details), else the directory it runs in, else none. Claude Code runs at the workspace root as a rule, so a session there is told at its start to claim its project; claim paths resolve under the project’s directory, and a claim covers the same place on a machine that keeps the workspace under another path. Only the launch and claude --project place a session before its first context, so only they scope the notes it starts with. Claude reads the project as that context’s heading (## ccdash knowledge: workspace / project); the prompt and the working directory stay as they are. A name the workspace has no directory for leaves the session where it is, and Claude is told.
  • A call is one round trip session → collector → hub with a 5 s budget.
  • doc_write carries the version the edit was based on, and the hub refuses a stale one, so a shared document never loses an edit silently.

3. Injections

The hooks add what matters to the session’s context:

WhenWhatSwitch
session startopen issues, relevant memories, documents, reports, recent progressinject.session_start
every promptother sessions active in the project, messages for itinject.prompt
before editing a filewho else edited it lately, claims covering itinject.edits

4. Offline

While the hub is unreachable, writes wait in the collector’s outbox (the tool says so) and are replayed in order when the link returns. Reads come from a cache of the live notes the hub pushes to every collector (~/.local/state/ccdash/notes-cache.json). A session that started during an outage catches up at its first prompt after the link returns.

5. Lifecycle

A daily pass marks memories stale when they were not verified for 90 days or not recalled for 60 (knowledge.stale_unverified_days, knowledge.stale_unrecalled_days; knowledge.reflect = false turns it off). Stale notes stay searchable but are no longer injected; the Projects page lists them to verify, rewrite or archive. A note that supersedes another retires it.

6. Import and export

ccdash import memory ~/code/work/.claude/memory              # one note per file, subdirectories too
ccdash import memory ~/code/work/.claude/memory/ops          # one subdirectory (its own MEMORY.md or INDEX.md)
ccdash import plan ~/code/work/meta/plans/x.md --project x   # doc, checkboxes as issues, log as progress
ccdash import plan ~/code/work/notes/design.md --doc --slug design   # the document alone
ccdash export --config /etc/ccdash/hub.toml ./notes          # every note as markdown

import runs on a workstation and sends through its collector; export reads the database (or a backup copy with --db) directly. Every import is safe to rerun: an unchanged file changes nothing, and a note the hub changed after the file’s modification time is kept (the report counts it as kept). A memory’s title is its index line’s, its summary the frontmatter description or the index hook when that says more; status: archived in the frontmatter retires the note, so an export imports back as it was. A plan’s checkbox is keyed by its section and text: tick it without rewording it.

Reports

Sessions produce page-shaped work: a research write-up, a comparison, an audit, a dashboard. ccdash keeps those as reports: one self-contained HTML file in a shared design, published to the hub, read in the panel, searched like any note and downloaded to send on.

  1. What a report is
  2. Making one
  3. Publishing
  4. Reading, searching, sharing
  5. Storage
  6. Security
  7. Configuration

1. What a report is

A report is a note of kind report (knowledge) with an HTML file behind it. The note holds the title, a one-line summary and an abstract in markdown (the question, the findings with their numbers, the recommendation), so recall, the session-start context and the search tell the story without opening the file; extra keeps the file’s size, hash, the machine it came from and where it was there. The file is the whole report: inline styles and scripts, images as data: URIs, nothing fetched from the network, so it reads the same in the panel’s frame, as a file sent to someone, and offline.

Every report wears the same chrome, the ccdash:report skill’s template.html: a top bar with the title, the date and a search box (matches marked in the text and listed under the box with their section, the contents narrowed to the sections that hit, Enter and the arrows step through them, / focuses it); a System/Light/Dark switch that follows the system until picked and, when framed, follows the panel’s mode and wears the panel’s colour scheme (Neutral, Catppuccin, the wallpaper’s…); a text size switch, Small/Normal/Big (the whole page scales; kept on the device, and in the panel the pick carries over to every report); the contents on the left (a drawer on the phone; the button beside the title hides the column on a wide screen, for a tall narrow monitor, and the choice is kept where storage allows), with the section in view marked; numbered headings; tables that sort by a click on a heading, with a filter box past eight rows; code blocks with colours, line numbers and Copy; print styles. On its own the report uses ccdash’s scheme in both modes; charts name the theme’s variables so they flip with it.

2. Making one

The ccdash:report skill (in the plugin the channel loads) is the procedure: write the article’s body as an HTML fragment, then

ccdash report build body.html --title "Hair dryer research (Alza.cz)" -o report.html

wraps it in the chrome, gives headings ids and refuses a body that fetches anything (<script src>, <link href>, an http image, url(http…), @import, a frame). --date sets the date shown (default: today). The components the chrome styles (tiles, tables, callouts, badges, figures) are in the skill’s reference.md.

3. Publishing

The report_publish tool, from the session that made the report:

ArgumentMeaning
paththe HTML file on the session’s machine (absolute, or relative to the session’s directory)
titledefault: the file’s <title>
slugdefault: from the title; publishing to an existing slug replaces that report (the note’s version grows)
summaryone line for lists
bodythe abstract, markdown; [[slug]] links as in any note
projectdefault: the session’s project
dateYYYY-MM-DD when it was made, for an older file (default: today); shown as “made …”

The collector reads the file and sends it with the metadata to the hub (PUT /reports/-/upload, this machine’s collector token), which checks it (an HTML document, self-contained, under reports.max_mb), keeps the file, writes the note and answers with the panel’s address. Unlike the other knowledge writes a report is not queued while the hub is unreachable (it is megabytes): the tool says so and the file stays where it is for another try. A slug that belongs to a note of another kind is refused.

The session’s chat shows a “Published a report” bubble where it happened, linking to the viewer.

From a shell, the same through the collector:

ccdash report publish report.html --title "…" --summary "…" --body-file abstract.md [--slug …] [--project …] [--date …]

Older reports on a machine come in with

ccdash report import --dry-run ~/ProjectBundle/tsandrini   # lists: title, date, slug, size; skipped files with the reason
ccdash report import ~/ProjectBundle/tsandrini/.claude-tmp/hair-dryer

which walks directories (node_modules, target, build and the like skipped), takes every HTML document that is self-contained, titles it by its <title>, dates it by the file’s modification time, and writes an abstract naming where it came from and its sections. Edit the note afterwards in the panel when the abstract should say more.

4. Reading, searching, sharing

Reports in the sidebar lists every report in the scope, newest first, by day, with the one note search narrowed to reports (title, summary and abstract). A report’s page frames the document, full height, with its abstract and facts in a drawer (▣), Download (the HTML file, to send on by hand), Open in a new tab, Load again; a new version published while the page is open reloads it; Archive takes a report out of the lists (the file stays; “archived too” on the Reports page shows them, Restore brings one back). Each project’s page has a Reports tab; the Projects overview counts them; Ctrl K finds them (kind report) and opens the viewer; the note itself (the abstract, its links, the graph) is one click away and has Open the report. The notes export puts a report’s .html next to its .md.

5. Storage

The files live under reports.dir (/var/lib/ccdash-hub/reports with the NixOS module) as <workspace>/<slug>.html, private to the ccdash user, outside the database and its nightly copies: back the directory up with a file-level tool, like the synced Claude state. A re-publish replaces the file in one step (written beside it, moved into place once the note is in). Archiving the note hides the report from the lists; the file stays. ccdash export writes the HTML next to each report’s markdown.

The chrome is baked into every file, so a change to the template reaches the reports published before it only by rebuilding them, on the hub:

sudo -u ccdash ccdash report rebuild --config /etc/ccdash/hub.toml --dry-run   # lists: outdated, current, foreign, missing
sudo -u ccdash ccdash report rebuild --config /etc/ccdash/hub.toml [workspace/slug …]

takes every report ccdash report build made apart, wraps the article in the current template and writes it back, after copying the file it replaces to .archive/<date>/<workspace>/<slug>.html under the reports directory (--archive DIR elsewhere); the note’s size and hash follow, its version and dates stay (the report did not change, its chrome did). Imported pages of their own design are left as they are. The hub need not stop: the files change in place, and the panel loads a report afresh each time it is opened.

6. Security

  • /reports/-/upload takes a collector’s token only.
  • The panel never gets the file’s address with its token: it asks POST /api/v1/reports/{ws}/{slug}/view for a view link, an HMAC over the workspace, the slug and an expiry an hour out, signed with a key drawn when the hub starts (a restart ends every link; the panel mints a new one when it loads a report). GET /reports/-/view/<key> serves the file under Content-Security-Policy: sandbox …; default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; img-src data: blob: …: the document is an opaque origin whether framed or opened in a tab, so a report’s scripts never reach the panel’s storage or token, and nothing loads from the network, which is the self-contained rule enforced a second time. The frame adds its own sandbox without allow-same-origin; links out of a report open in a new tab.
  • GET /api/v1/reports/{ws}/{slug}/file (the download) takes the bearer token like the rest of the API.
  • Anyone holding a panel token reads every report: keep the hub on the LAN or VPN (security).

7. Configuration

services.ccdash-hub.reports = {
  directory = "/var/lib/ccdash-hub/reports";  # default
  maxMb = 32;                                 # also sizes nginx's body limit on /reports/
};
# hub config
[reports]
# dir = "/var/lib/ccdash-hub/reports"   # default: reports/ next to the database
# max_mb = 32

Nothing on the collectors: report_publish uses the hub link and token they already have.

Machines and power

The Machines area shows the hub’s own machine and every node (a machine whose collector reports to the hub): uptime, CPU, memory, disks, battery. From there a node’s screen can be locked, and the node suspended and woken again over the LAN, so the phone can lock a forgotten desk, put it to sleep and bring it back.

  1. What a machine reports
  2. Lock
  3. Suspend
  4. Wake
  5. Asleep, waking, offline
  6. Configuration

1. What a machine reports

A collector reads its machine every 30 s, and once more right after a resume. The hub reads its own machine on the same schedule. Everything comes from /proc, /sys and getifaddrs, without privileges.

FieldSource
up, sleptCLOCK_BOOTTIME (sleep included), minus CLOCK_MONOTONIC (sleep excluded) for time slept
awake sincethe last resume the collector saw: the gap between the two clocks grew
CPUbusy share since the last reading (/proc/stat), load average, cores
temperaturek10temp Tctl, zenpower Tdie, coretemp package, cpu_thermal, the first found
memorytotal minus available, swap used (/proc/meminfo)
disksstatvfs of / and $HOME (the hub: / and its database’s directory), one per device
batterythe first power_supply of type Battery that is not a device’s (a mouse), mains online
systemPRETTY_NAME, the kernel, reboot pending (NixOS: the booted and current systems differ)
networkphysical wired cards: MAC, IPv4 addresses, whether power/wakeup is on (wake-on-LAN)
screenlogind’s LockedHint of the user’s display session, which the screen locker sets
can suspendthe collector’s power.suspend, power.lock

The hub keeps every node’s last report and status in its database. After a restart, Machines still lists every node it has seen, offline ones too, and still knows how to wake them. Forget on an offline node’s page drops it until its collector connects again.

2. Lock

Lock is opt-in per machine (power.lock). A node whose screen is unlocked says so on its card, in amber, with a Lock button; its page has Lock too. Locking asks nothing first: it only protects.

The collector finds the user’s graphical session (logind’s Display) and runs power.lock_command, by default loginctl lock-session <id>. Any screen locker that listens to logind answers it; DankMaterialShell does with its loginctl integration on, which is its default. The report that follows a moment later says whether the screen is locked now. A machine without a graphical session refuses with that reason.

3. Suspend

Suspend is opt-in per machine (power.suspend). On a node’s page, Suspend… asks first. The dialog says whether the hub can wake the machine again and names the sessions mid-turn that would pause.

  • First the hub checks it may: it refuses (409) when the machine is offline, has not opted in, is already on its way to sleep, or, unless forced, when a session there is working or waits on a prompt. The panel’s dialog forces it after naming those sessions.
  • The collector lets the state sync hand the hub what is pending (up to 12 s), then runs power.suspend_command (systemctl suspend), which returns once the sleep is on its way.
  • It answers before the freeze. A refusal (an inhibitor, logind’s policy) comes back to the panel word for word. Otherwise the hub marks the machine asleep. If the link drops before the answer, the freeze came first and the hub marks it asleep all the same.

logind lets the user of an active seat session suspend without a password, and that includes a process of the user’s systemd manager (the collector’s service). No polkit rule is needed.

4. Wake

The hub sends the magic packet itself: six 0xff bytes and the MAC sixteen times, as UDP to port 9, three times 300 ms apart. It needs neither a wakeonlan binary nor router credentials.

It learns where to send from the reports, so no MAC is ever typed:

  • From the node’s last report it takes the wired cards with wake-on-LAN on. A card that lost its addresses on the way to sleep keeps the ones it had.
  • If the hub has an address on one of those cards’ networks, the packet goes to that network’s broadcast address, for example 10.10.0.255.
  • Otherwise it goes to wake.via.<host>, if that is set: an address the hub routes to.
  • Otherwise the node cannot be woken from the hub. Its page says why, for example “the hub has no address on 192.168.31.0/24”.

A magic packet must arrive as a frame on the sleeping machine’s own network. A tunnel to the machine itself (its WireGuard peer) sleeps with its kernel. For a machine on another network, the router in front of it has to put the routed packet onto that network, in one of two ways:

  • Unicast to the machine’s address, with a permanent ARP entry for it on that router (a sleeping machine answers no ARP). Set wake.via.<host> = "<its address>".
  • A directed broadcast (<its network>.255), which the router forwards onto that network. Linux: net.ipv4.conf.<if>.bc_forwarding. RouterOS: /ip settings and the firewall. Set wake.via.<host> = "<network broadcast>".

Either way the hub’s packets need a route to that address, and the firewalls on the way must let UDP to port 9 through.

5. Asleep, waking, offline

StateShown asEnds
connectedgreen, “connected for …”the link drops
asleepamber, “asleep since …” (suspended here)the machine connects again, or reports again 15 s later
wakingamber, “waking for …”it connects; after 3 min the panel offers Wake again
offlinered, “offline for …”, the last report fadedit connects

A machine suspended by hand shows as offline until it resumes. Its page then tells how long it slept and when it woke. After a sleep of 30 s or more, the collector reconnects at once instead of waiting for its next ping to fail. The hub forgets an unanswered wake after 10 minutes.

6. Configuration

WhereKeyDefaultMeaning
collectorpower.lockfalsecarry out the panel’s Lock
collectorpower.lock_command["loginctl", "lock-session", "{session}"]locks; {session} is the display session’s id
collectorpower.suspendfalsecarry out the panel’s Suspend
collectorpower.suspend_command["systemctl", "suspend"]suspends; must return once the sleep is on its way
hubwake.via.<host>—ip or ip:port the packets go to when no network is shared
Home Managerservices.ccdash.power.lockfalsesets power.lock
Home Managerservices.ccdash.power.suspendfalsesets power.suspend
NixOS (hub)services.ccdash-hub.settings.wake.via{ }sets wake.via

The hub’s service allows AF_NETLINK so that getifaddrs can list its own networks. Wake-on-LAN itself is the machine’s setup: on NixOS, networking.interfaces.<if>.wakeOnLan.enable with the magic policy and the firmware’s wake setting.

Sessions on every machine (state sync)

With sync on, the hub keeps Claude Code’s state for every machine and each collector keeps its machine’s copy in step: a session ended on one machine resumes on another with a plain claude --resume (the picker lists it), and the up arrow and Ctrl+R know the prompts of every machine. The panel’s Sessions › Past searches every machine’s transcripts and resumes one on the machine you pick (sessions).

  1. Turning it on
  2. What travels
  3. How files travel
  4. One session, one machine
  5. Conflicts
  6. The State page
  7. On the hub

1. Turning it on

services.ccdash.sync.enable = true;   # Home Manager, on every workstation

Claude Code files a session under the directory it started in and finds it again by its id from any directory. So the machines need neither the same user nor the same paths: what has to match is the workspace, of which the hub knows each machine’s directory (installation), and the layout below it. A session resumed on a machine with other paths goes on under its own id, in that machine’s directory of the workspace; its transcript stays where the first machine filed it, and its earlier tool calls keep the paths they ran with.

2. What travels

Travels (relative to ~/.claude)Stays on each machine
projects/ (transcripts, subagents, tool results, auto memory)credentials, ~/.claude.json
file-history/ (rewind checkpoints)settings, plugins, skills (Nix and your repos carry those)
plans/, tasks/, paste-cache/the running-session registry, background jobs, shell snapshots
history.jsonl (prompt history)projects/-tmp-* (scratch sessions)

3. How files travel

  • Changes come from inotify (a watch per directory that can hold synced files); a burst of writes settles for a quarter second (two at most), then just those files are handled. Everything is scanned at start-up, after an inotify overflow, for Resync and Stop, and every half hour as a safety net. Without inotify the collector scans every interval_secs.
  • Byte for byte: a file that only grew sends its new tail; a transcript line still being written waits. The hub refuses a write made against a version it no longer has, so nothing is overwritten unseen.
  • Deletions never travel: Claude Code’s clean-up (cleanupPeriodDays) on one machine removes nothing elsewhere, and the hub keeps everything.
  • Prompt history merges line by line: lines from other machines are appended, the file is never rewritten.
  • Running sessions: the files of a session running on a machine are never written there; they catch up when it ends.
  • Name lookups of the hub are reused for 5 minutes, so a backfill does not flood the DNS server.

Measured on 6,430 files (2.4 GB) with a hub on the same machine: a backfill takes about 15 s, a second machine compares everything in under 3 s, and an idle collector uses no measurable CPU.

4. One session, one machine

A resumed session goes on in the same transcript, so two machines with it open would split it. The hub knows where each session is open:

  • In a session another machine opened first and still has open, prompts are refused: the hook blocks them and says where, with a link. A resume shows a warning first.
  • The hub refuses that machine’s writes to the session’s files (a blocked prompt still writes bookkeeping lines).
  • End the session there (its Kill, or Forget when that machine is offline), then send the prompt again. If the other machine added to the session after it was opened here, the hook asks you to quit and resume it, to load the whole conversation.

5. Conflicts

A file changed on both sides between two syncs is a conflict. The hub’s version stays in place everywhere; the machine keeps its own as a copy under ~/.claude/ccdash-conflicts/<time>/…. A transcript copy still opens with claude --resume <path>.

ActionEffect
Keep the current versionthe machine deletes its copy
Use the copythe copy replaces the version on every machine; the replaced one becomes the copy, so the choice can be undone
Hidethe conflict leaves the list; the copy stays

Each conflict shows how the two versions compare: the bytes they share, the lines each has after that, and when each was written. The collector reports every copy it holds after each full scan, so a copy deleted by hand resolves its conflict.

6. The State page

  • Machines: each machine’s copy (files, what waits, the first run’s progress, whether it watches files) with Resync, which compares every file with the hub again, sends what the hub lacks and fetches what the machine lacks, deleted files included.
  • Conflicts with the actions above.
  • Sizes: by kind of file, by project and the largest sessions.
  • Growth: per day and project, counted from the first write the hub records (a backfilled file counts on the day it was last written), and what grows fastest.

7. On the hub

The files are plain files under sync.dir (/var/lib/ccdash-hub/claude with the NixOS module), outside the database and its nightly copies: back the directory up with a file-level tool (restic encrypts). The /sync/ routes take the collectors’ tokens and pieces of up to 8 MiB; the NixOS module raises nginx’s body limit there.

# collector config
[sync]
enable = true
# root = "~/.claude"              # default: $CLAUDE_CONFIG_DIR, else ~/.claude
# include = ["projects/*", "file-history/*", "plans/*", "tasks/*",
#            "paste-cache/*", "history.jsonl"]
# exclude = ["projects/-tmp-*"]
# interval_secs = 3               # full scans, only without inotify

# hub config
[sync]
# dir = "/var/lib/ccdash-hub/claude"  # default: claude/ next to the database

The workspace on every machine (workspace sync)

With the workspace sync on, the workspace root (workspace.root, such as ~/code: every git repository and plain directory under it) behaves like one directory that happens to be visible on every machine. A file saved on one machine is on the others within a second; a branch switch, a staged file and a stash follow; two sessions on two machines editing one repository collide only where two sessions on one machine would (the same hunk), and that collision is an ordinary git conflict marker plus an entry in the panel. Nothing to run by hand.

  1. Turning it on
  2. Units
  3. How a change travels
  4. What stays home
  5. Conflicts, held snapshots, diverged branches
  6. A new machine, an existing copy
  7. The Workspace area
  8. On the hub
  9. Costs

1. Turning it on

services.ccdash-hub.workspace.enable = true;   # NixOS, the hub
services.ccdash.workspace = {                  # Home Manager, every workstation
  enable = true;
  root = "~/code";                             # no default
  include = [ "work/*" "me/*" ];               # globs on unit ids, empty = everything
  exclude = [ "me/nixpkgs" "*_bkp" ];
};

The Home Manager options are the starting configuration: the first collector to reach a hub without one hands it over, and from then on the hub owns the configuration and the panel edits it (Workspace › Configuration). Every machine needs the same user and the same root path.

2. Units

A unit is a directory under the root that travels as one git-shaped thing:

UnitExampleHow
a repository at unit depth (<bundle>/<repo>)tsandrini/ccdashits own .git
a bundle root that is a repositorytsandrini (with .claude/, meta/)the same; the directories that are units of their own are left out of its tree by pathspec
a repository nested deepermeteopress/livance/nestedits own unit; the parent leaves the directory alone (an existing gitlink stays as it is)
a plain directory at unit depthmeteopress/tmp (in a bundle without .git)a hidden repository under $XDG_STATE_HOME/ccdash/workspace/<unit>.git with core.worktree set

A plain directory inside a bundle-root repository is part of that repository’s unit, not a unit of its own. Dot-directories count. Unit ids are paths relative to the root, /-separated; include and exclude are globs on them (* spans /), exclude wins, a per-unit override in the panel wins over both.

A directory that appears at unit depth and is not configured is new: the collector reports it with its size (working tree plus .git, the never-travelling directories left out); the hub includes it by itself when it is under the threshold (500 MB, per bundle in the configuration) and otherwise lists it on the Workspace page for a tap (Include or Ignore). A unit whose directory disappears on one host shows as missing there; the directory is never deleted elsewhere.

3. How a change travels

One inotify instance watches every directory of every unit that is not ignored (79,592 on a 1.3 M-file workspace, registered in 0.11 s), each unit’s .git and its refs, and the root and bundle directories for units appearing. A new directory is checked with git check-ignore before it is watched, so an npm install costs two events. A burst settles for 250 ms (2 s at most under a steady stream); then the unit’s pass runs on one of four worker threads (a unit is in one pass at a time):

  • Snapshot. The real index is copied to a temporary one; git add -A into it (plus git add -f for the opted-in ignored paths, with the directories of nested units and untracked files over max_file_mb excluded by pathspec) gives the work tree; write-tree on another copy of the real index gives the index tree (the staged state). A commit whose tree holds both (work/, index/) is made on this host’s chain (refs/sync/<host>, the first one off HEAD) with a message carrying HEAD, the branch, every branch, tag and remote-tracking ref (refs/remotes/*: what git status compares against, so “ahead by 3” reads the same on every machine), the stashes and the empty directories. Nothing changed → no commit. The real index is never written by a snapshot.
  • Push. refs/sync/<host> goes to the hub’s bare repository of the unit over git smart HTTP with the collector token, together with the branch tips, tags and stashes under refs/sync-tips/<host>/… so their objects travel. The hub tells the other collectors (WorkspaceChanged).
  • Apply on the other machines, after their own fresh snapshot L: fetch refs/sync/<other> as S, merge-base L S. S already in → nothing. L is the base → fast-forward: read-tree -u -m moves the working tree to S’s, the index becomes S’s staged state, HEAD and the branches follow, refs/sync/<me> becomes S. Otherwise merge: merge-tree --write-tree of the two snapshot trees on the base (the staged states merge in the same call; a path staged differently on both sides ends unstaged), the result is applied the same way and a two-parent commit becomes refs/sync/<me>, pushed so the other side fast-forwards. read-tree -u -m refuses when a file changed underneath; the pass ends and the next event retries. Files are written through git’s atomic rename; the executable bit and symlinks travel, mtimes become “now”, empty directories are recreated.
  • HEAD, branches, stashes. HEAD and the checked-out branch follow the snapshot (rewinds included); every other branch and tag is set to the snapshot’s value; a branch moved on both sides since the base stays as it is here and the other tip is kept under refs/sync/diverged/<host>/<branch>. Remote-tracking refs follow the machine that fetched further; one that moved apart on both sides (the remote was rewritten between two fetches) stays as it is here and is never shown as diverged, the next git fetch settles it. Stashes from the snapshot are recreated when missing (git stash store).
  • Remotes and upstreams. A repository’s snapshot also carries its remotes (remote.<name>.url, pushurl, fetch, push) and branch upstreams (branch.<name>.remote, merge, pushRemote); nothing else from .git/config travels. A remote whose URL holds a password or a token (https://user:token@…, or any user in an http(s) URL) stays home, and so does every upstream naming it. The other machines only add: a remote, or a branch’s upstream, they lack entirely is written; one they have in any form is never changed or removed, so two machines may keep different URLs for good. A unit created from the hub fetches and pushes like the copy it came from. A changed remote alone makes no snapshot (two machines that disagree on a URL would take turns for ever): it rides along with the next one, or with ccdash workspace resync. A resync also adds what the other machines’ snapshots on the hub carry and this copy lacks: run it once on every machine after the update that made remotes travel (older snapshots carry none), or after another git held config.lock during an apply.

Every git call the collector makes runs with core.excludesFile set to the never-travelling list, core.hooksPath pointing at an empty directory (a pre-push hook would otherwise run on every sync push), gc.auto off, no credential helpers, no prompts, stdin closed, a timeout, and the hub token in GIT_CONFIG_* environment variables, never on the command line. Nothing is written into a repository’s configuration but the remotes and upstreams it lacks (above).

Left alone until done: units with index.lock, a merge, rebase, cherry-pick or bisect in progress; applies while a live Claude Code session’s tool call is in flight on this host (PreToolUse without PostToolUse, stale after 10 minutes). Safety nets: a sweep of every unit at start, after an inotify overflow and every 30 minutes; every unit’s remote refs fetched every 5 minutes. Hub down: nothing moves, work continues, the next connection merges.

4. What stays home

  • Never, whatever the configuration (always_exclude, by directory name anywhere): node_modules, .venv, venv, .direnv, .devenv, target, result, result-*, __pycache__, .cache. Store symlinks point into another machine’s /nix/store; build trees are rewritten by every build.
  • Opted in (sync_ignored, per configuration, bundle or unit; the Workspace page’s unit view lists the ignored directories present with their size and a switch each): gitignored files and directories that travel anyway, by default .env, .env.*, .envrc.local. A node_modules can be carried this way (measured: 38k files hashed in 2 s the first time, 81 MB on the hub, 0.7 s per quiet pass afterwards).
  • Quiescent (the default for anything under .devenv/state, a flag on any sync_ignored entry): snapshotted only while no process on this host holds a file under it open (/proc/*/fd), and written only under the same condition; otherwise the unit shows “waiting: postgres holds … open” and the directory keeps its content while everything else in the unit moves on. The snapshot still carries the other machine’s version, and the directory catches up within 15 seconds of the process letting go. A dev database travels when its server is down, never under a live one.
  • Untracked files above max_file_mb (64) are skipped and listed.
  • refs/sync/* and refs/sync-tips/* are visible in git log --all and for-each-ref, like remote-tracking refs.

5. Conflicts, held snapshots, diverged branches

  • Text conflict: the file gets standard markers (<<<<<<< refs/sync/<me> … >>>>>>> refs/sync/<other>), every other file merges clean, and the hub records the conflict with both blobs. It is open until the markers are gone (the next snapshot notices) or the panel’s Keep mine / Take theirs writes one side. Dismiss hides the entry. A unit (or the whole configuration) can choose set_aside instead: the local version stays and the other side is only on the hub.
  • Binary conflict: the local version stays; the other blob is on the hub, shown and chosen in the panel.
  • Held snapshot: a snapshot that would add or delete more than 2,000 files, or a fifth of a unit with at least 100 tracked files, in one settle does not travel. The unit shows held with the numbers, a push notification asks, and the panel’s Apply pushes it as it is while Drop puts the working tree back to the previous snapshot. The guard against a generator writing into the tree and against an accidental rm -rf.
  • Diverged branch: main committed on two hosts within one window. The local branch stays, the other tip is refs/sync/diverged/<host>/main, the unit view shows both for you to merge or rebase by hand; the working trees still merge.

6. A new machine, an existing copy

  • Init (a machine without the workspace): once the collector connects, every unit the hub has and this machine lacks is created (an empty repository fast-forwarded to the newest snapshot, branches, HEAD and staged state included), in parallel, under the same resource limits. ccdash workspace init does the same now and ccdash workspace status follows it. An 800 MB history takes 20 s on the LAN and 80 s over the tunnel.
  • Adopt (a machine with its own copy of the workspace): a unit that exists here and already has snapshots on the hub from another machine is not touched until you say so — it shows as “to adopt” with the hint; so does a copy whose first snapshot never reached the hub. ccdash workspace adopt [unit] (or Adopt here on the unit view) takes the first snapshot and merges it with the hub’s latest: a repository merges on the commit both copies share (edits since then from both sides, a deletion stays deleted, the same lines changed on both sides end as markers), a plain directory has no common base and merges as a union. When one copy is simply older than the other, merge nothing: --prefer hub makes this copy exactly the hub’s content (its own branch tips are kept under refs/sync/diverged/<this machine>/… when they are not behind), --prefer mine makes the hub’s content exactly this copy’s and the other machines fast-forward to it. Measured on a 219-unit copy: 2.5–4 minutes, 33–42 real merges, one genuine conflict.
  • A unit that exists only here with nothing on the hub is seeded without a question.
ccdash workspace status [unit] [--json]   # every unit's state on this machine
ccdash workspace resync [unit]            # fetch and snapshot again, remotes and upstreams included
ccdash workspace init                     # create what the hub has and this machine lacks
ccdash workspace adopt [unit] [--prefer mine|hub]   # copies that exist on both sides: merge, or one side wins

7. The Workspace area

Sections, as tabs:

  • Overview: the tiles (units and how many are in step everywhere, machines connected and the slowest link’s round trip, what needs you, what the hub holds and what landed today, the last day’s traffic and CPU), what needs you (held snapshots with Apply and Drop, conflicts with both versions and Keep mine / Take theirs / Dismiss, new directories over the threshold with Include and Ignore — or one quiet line), the machines in a line each with Resync, the last 24 hours of traffic per machine, the units that changed last.
  • Units: a table that sorts by its columns (unit, kind, state, size, pushes, last push), a search over unit ids, states and details, filters (needs you, conflicts, held, failing, to adopt, moving, paused, changed today), and one compact chip per machine with the state as its colour (the full state when the bar picks one machine); the new directories; the held snapshots; the conflicts. A unit opens its page (/workspace/unit/<unit>): the state on every machine with the snapshot id and the last pass, diverged branches, its conflicts, the ignored directories present with a switch each, overrides (size limit, conflict shape, pause, exclude) and the snapshot history (host, time, files changed, branch, merges).
  • Machines: a card per collector — the link (connected since, the round trip of the hub’s WebSocket ping), the collector (root, units, in step, moving, a seed’s progress, errors), traffic today and over seven days (bytes up and down, requests, the mean push time, failures), the large transfers’ throughput (median and best rate of transfers over 64 kB: the uplink question), today’s cost (CPU seconds and the share of one core, passes, git calls, disk I/O), what is resident now and how many watches are held. Below, bytes per hour per machine and every large transfer of the week with its rate.
  • Statistics (the range in the bar, a year back at most): a per-machine table (pushes, fetches, bytes, CPU, share of one core, disk I/O, peak resident set, failures), traffic and pushes per bucket stacked by machine, CPU seconds per bucket, the collectors’ peak resident set, the hub’s largest repositories, conflicts per bucket. Hourly buckets up to three days, daily beyond.
  • Configuration: the rules, open: include and exclude globs as rows with a match count each (“8 units”, “matches nothing”); the never-travelling names with what each keeps home (“node_modules: 12 GB in 31 units”); the paths that travel although ignored with the quiescent flag; depth, the size caps, the conflict shape, the per-bundle thresholds. The hub previews a draft as you type (the decision shown for every directory is the hub’s own), and says how many units would start or stop travelling before you save. Then Coverage: per machine, what the root holds, what travels and what stays home; the never-travelling names by what they keep home; every directory at unit depth that does not travel with its size and why (excluded by *_bkp, matched by no include glob, over the threshold, ignored by you, a linked worktree that cannot travel), with Include and Ignore; the gitignored directories inside travelling units, largest first.
  • The bar’s workspace and host filters apply: a workspace is a bundle here, so picking one shows that bundle’s units, new directories, held snapshots and conflicts; picking a machine shows its column alone.
  • Push notifications: a held snapshot, a conflict, a new directory over the threshold, a unit failing for more than 10 minutes — each a kind a device can mute in Settings (notifications).

8. On the hub

One bare repository per unit under sync.dir/workspace/<unit>.git (/var/lib/ccdash-hub/claude/workspace/ with the NixOS module, which puts restic over it), created on the first push with http.receivepack, receive.shallowUpdate (69 of 219 real units are shallow clones), gc.auto off and a shared pre-receive guard. The smart HTTP routes /git/<unit>.git/{info/refs,git-upload-pack,git-receive-pack} take the collector tokens and spawn git http-backend as CGI with the body streamed both ways; the NixOS module’s nginx location has client_max_body_size 0 and proxy_request_buffering off.

The guard makes merges compare-and-swap: a push to refs/sync/<host> of a commit with more than one parent is accepted only if every extra parent is the current tip of another host’s ref; otherwise it is refused with the tips, the collector fetches and merges again, and since identical inputs give identical trees the second round converges. Without it three hosts merging the same pair at once re-triggered one conflict eight times. Plain snapshots are never refused.

Tables: workspace_units (unit, bundle, kind, state, size, version), workspace_refs (host → snapshot per unit), workspace_conflicts, workspace_events (pushes with their bytes, the growth), workspace_config (the one configuration, versioned), workspace_seen (what each host sees at unit depth, with the bytes under each never-travelling name and why a directory cannot be a unit), workspace_traffic (per host, hour and direction: requests, bytes in and out, time, failures), workspace_cost (per host and hour: the sync’s CPU, git’s CPU, calls, disk I/O, passes, snapshots, pushes, fetches, failures, the peak resident set, the watches), workspace_transfers (the last 300 transfers over 64 kB). ccdash gc runs git gc --quiet over every repository; the module’s timer runs it nightly at 03:30. Snapshot history is kept whole for now; retention is a later knob; traffic and cost rows are kept for a year.

The collector resolves the hub’s name once per link (and again five minutes later, or after a reconnect) and hands every git call the address as http.curloptResolve, so an adopt burst makes no DNS lookups and pushes keep working while the resolver is unhappy (the last answer stands).

# hub config
[workspace]
enable = true

# collector config
[workspace]
enable = true
root = "~/code"
# depth = 2
# include = ["tsandrini/*"]
# exclude = ["tsandrini/nixpkgs"]
# always_exclude = ["node_modules", ".venv", "venv", ".direnv", ".devenv", "target", "result", "result-*", "__pycache__", ".cache"]
# sync_ignored = [".env", ".env.*", ".envrc.local"]
# max_file_mb = 64
# auto_include_mb = 500

9. Costs

Every collector counts what the sync costs it: the CPU time of its own threads (RUSAGE_THREAD per job) and of every git process it ran (reaped with wait4: CPU, block I/O, peak resident set), the passes, snapshots, pushes and fetches with their wall time, failures, plus its resident set and the inotify watches it holds. The hub folds the deltas into hourly rows per machine (a restarted collector’s counters are the delta); the smart HTTP route records every request’s bytes, time and outcome per machine and hour, and the transfers over 64 kB on their own. The Machines and Statistics sections show them; ccdash workspace status --json prints the live counters under cost.

Measured on the real fleet (meta/plans/workspace-sync/research.md in the owner’s workspace) with the collector’s unit at CPUWeight=20, IOWeight=20, Nice=10, which the Home Manager module sets: idle 0.04 % of one core on the busiest workstation, under 1 % during real work (120 edits, a vite dev server, an npm install of 38k files, 9k files written into an ignored target/), 26 MiB resident; the Pi hub at 2–4 % of one core while three machines work, 1.1–1.25 cores only during a seed. End to end: a one-line edit lands on the other machine in ~50 ms over the LAN and ~170 ms over WireGuard. A seed of 219 units (13 GB) takes about 4 minutes; an adoption reads the copy once (12–17 GB) and takes 2.5–4 minutes.

Configuration

Both daemons read TOML (--config, else $XDG_CONFIG_HOME/ccdash/config.toml; on Windows %APPDATA%\ccdash\config.toml) and reject unknown keys. The Nix modules write the files, and on Windows the script the collector’s: their options cover the common keys, settings takes the rest. In paths, $VAR and ${VAR} expand.

  1. NixOS module (hub)
  2. Home Manager module (collector)
  3. Hub keys
  4. Collector keys

1. NixOS module (hub)

services.ccdash-hub.* runs the hub; programs.ccdash.channel.allow (the default NixOS module) allowlists the channel plugin in Claude Code’s managed settings. Every option with its type, default and example, generated from the module: hub module options.

2. Home Manager module (collector)

services.ccdash.* runs the collector and wires Claude Code to it (hooks, the plugin, the channel wrapper, the statusline). Every option, generated from the module: Home Manager module options.

3. Hub keys

KeyDefaultMeaning
hostthe kernel’s host namethe name the panel shows for the hub
http.listen["127.0.0.1:7837"]addresses of the API and the panel
http.token_filegenerated in the state dirthe bootstrap token
http.public_urlLAN address and first portwhere phones open the panel (links, pairing)
http.web_dirthe built panelthe panel’s files
collect.tokens{}host name → collector token file
store.path<state dir>/ccdash.dbthe database
store.retention_days30history kept
store.tool_output_bytes8192Bash output kept per call (0 keeps none)
workspaces.dirs[]the workspaces: a path, ~/… under each machine’s home, or a relative path under each machine’s workspace.root
notify.delay_secs, .focused_delay_secs15, 120how long a prompt waits before it notifies
notify.permissions, .questions, .plans, .turnstruewhat notifies
notify.workspaces[] (all)only these workspaces notify
notify.web_urlhttp.public_urlwhere notification taps lead
push.enabledtrueWeb Push
push.subject, .ttl_secs, .key_filepublic URL, 3600, state dirVAPID contact, message lifetime, key pair
knowledge.reflecttruethe daily staleness pass
knowledge.stale_unverified_days, .stale_unrecalled_days90, 60when memories turn stale
sync.dirclaude/ next to the databasethe synced files
workspace.enablefalsethe workspace sync (repositories under sync.dir/workspace)
reports.dirreports/ next to the databasethe published reports’ HTML files
reports.max_mb32the largest report taken
attachments.enable, .dirtrue, attachments/ next to the databasefiles attached to prompts (attachments)
attachments.max_image_mb, .max_audio_mb, .max_video_mb, .max_file_mb25, 50, 300, 50the largest file taken, by kind
attachments.quota_mb, .retention_days5120, 30all attachments together; days until an unkept one is dropped (0: no bound)
wake.via.<host>—where magic packets go for a machine on another network (machines)

4. Collector keys

KeyDefaultMeaning
hostthe kernel’s host namemust match a key of the hub’s collect.tokens
hub.url, hub.token_file—the hub’s /collect endpoint, this machine’s token
agents.command, .interval_secs["claude","agents","--json","--all"], 5the liveness poll
usage.command, .interval_secs["claude"], 600the /usage poll ([] is off)
skills.plugin_dirs[] (the ccdash plugin when the channel is on)plugin directories sessions start with; their skills join the composer’s / menu
launch.command["claude"]starts sessions from the panel ([] is off)
launch.channelfalselaunched sessions load the ccdash channel (--channels)
launch.stop, .removeclaude stop {id}, claude rm {id}stop a background session; remove one nothing runs
launch.direnv, .env[], []direnv export json in the launch dir; the globs of the variables launched sessions get
attach.command[] (off)opens a background session in a terminal ({id}: its short id)
edit.command[] (off)opens a draft from the panel in an editor; {file} is its path
attachments.enable, .dir, .keep_daystrue, attachments/ in the state directory, 7fetches a prompt’s attached files for this machine’s sessions; days an unused one stays
transcribe.command, .timeout_secs, .attachments[] (off), 300, trueputs recordings into words: dictation, and attached recordings and videos (attachments)
video.ffmpeg, .frames, .edge, .timeout_secs"" (off), 12, 1568, 300cuts still frames from attached videos (attachments)
niri.enable, .terminalstrue, common terminals’ app idswindow focus and which windows are terminals
procs.enable, .interval_secstrue, 5CPU and memory sampling
telemetry.listen[]OTLP receiver (loopback only)
queue.max_bytes32 MiBthe outbox while the hub is unreachable
inject.session_start, .prompt, .editstruethe knowledge injections
sync.enablefalsethe state sync
sync.root$CLAUDE_CONFIG_DIR, else ~/.claudewhat is kept in step
sync.include, .excludesee state syncwhat travels
sync.interval_secs3full scans, only without inotify
workspace.enable, .rootfalse, —the workspace sync and its root (~/ and $VAR expand); the hub’s relative workspaces are under the root, sync or not
workspace.depth2units at <root>/<bundle>/<repo>
workspace.include, .exclude[], []globs on unit ids; the starting configuration a hub without one takes
workspace.always_excludesee workspacedirectory names that never travel
workspace.sync_ignored[".env", ".env.*", ".envrc.local"]gitignored paths that travel anyway (.devenv/state/* quiescent)
workspace.max_file_mb, .auto_include_mb64, 500the untracked file cap, the new-directory threshold
power.suspendfalsecarry out the panel’s Suspend
power.suspend_command["systemctl", "suspend"]suspends; returns once the sleep is on its way
power.lockfalsecarry out the panel’s Lock
power.lock_command["loginctl", "lock-session", "{session}"]locks the user’s display session ({session}: its id)

On Windows host defaults to the DNS host name, lowercased; niri.enable to false; power.lock_command to ["rundll32.exe", "user32.dll,LockWorkStation"]; and power.suspend_command to a hidden PowerShell calling SetSuspendState (sleep, not hibernation).

Hub module options

The NixOS modules: nixosModules.hub (services.ccdash-hub) runs the hub, nixosModules.default (programs.ccdash) allowlists the channel. Generated from the modules; keys the options do not cover go into settings (configuration).

programs.ccdash.channel.allow

Whether to enable the ccdash channel in Claude Code’s managed settings (/etc/claude-code/managed-settings.d/ccdash.json), so sessions started by the home-manager module’s claude wrapper load it without the development-channel warning. This replaces Anthropic’s default channel allowlist on this machine; list any other channel plugins you use in allowedChannelPlugins yourself .

Type: boolean

Default:

false

Example:

true

Declared by:

services.ccdash-hub.enable

Whether to enable the ccdash hub.

Type: boolean

Default:

false

Example:

true

Declared by:

services.ccdash-hub.package

The ccdash package.

Type: package

Default:

ccdash.packages.${system}.ccdash

Declared by:

services.ccdash-hub.attachments.enable

Whether the panel can attach files to prompts (photos, recordings, documents): the hub keeps them as plain files until a session’s machine fetches them, within the bounds below. Off, the panel offers no attaching and its Files area is gone.

Type: boolean

Default:

true

Declared by:

services.ccdash-hub.attachments.directory

Where the hub keeps attached files, outside the database and its nightly copies.

Type: string

Default:

"/var/lib/ccdash-hub/attachments"

Declared by:

services.ccdash-hub.attachments.maxAudioMb

The largest sound recording taken, in MiB.

Type: positive integer, meaning >0

Default:

50

Declared by:

services.ccdash-hub.attachments.maxFileMb

The largest file of any other kind taken, in MiB.

Type: positive integer, meaning >0

Default:

50

Declared by:

services.ccdash-hub.attachments.maxImageMb

The largest picture taken, in MiB.

Type: positive integer, meaning >0

Default:

25

Declared by:

services.ccdash-hub.attachments.maxVideoMb

The largest video taken, in MiB.

Type: positive integer, meaning >0

Default:

300

Declared by:

services.ccdash-hub.attachments.quotaMb

All attachments together, in MiB: over it the oldest ones not marked Keep go first. 0 sets no quota.

Type: unsigned integer, meaning >=0

Default:

5120

Declared by:

services.ccdash-hub.attachments.retentionDays

Attachments not marked Keep are dropped this many days after their upload. 0 keeps them until the quota or the owner removes them.

Type: unsigned integer, meaning >=0

Default:

30

Declared by:

services.ccdash-hub.backup.enable

Whether to enable a nightly copy of the database through SQLite’s backup API, checked with PRAGMA integrity_check, kept in directory for a file-level backup tool (restic, say) to pick up .

Type: boolean

Default:

false

Example:

true

Declared by:

services.ccdash-hub.backup.directory

Where the copies go.

Type: string

Default:

"/var/lib/ccdash-hub/backups"

Declared by:

services.ccdash-hub.backup.keep

How many daily copies to keep.

Type: positive integer, meaning >0

Default:

7

Declared by:

services.ccdash-hub.backup.onCalendar

When to copy (systemd.time(7)).

Type: string

Default:

"*-*-* 03:30:00"

Declared by:

services.ccdash-hub.collectors

Collector token files by host name: the name each collector announces, and the file holding the token it must send. Readable by the ccdash user.

Type: attribute set of string

Default:

{ }

Example:

{
  desk = "/run/agenix/ccdash-collector-desk";
  laptop = "/run/agenix/ccdash-collector-laptop";
}

Declared by:

services.ccdash-hub.localCollector.enable

Whether to enable a collector on this machine too (a single node: the hub and a workstation in one). Generates its token once into /var/lib/ccdash-hub-local/collector.token, readable by user and the hub, and lists it under host; the home-manager module’s services.ccdash.hub.local picks it up .

Type: boolean

Default:

false

Example:

true

Declared by:

services.ccdash-hub.localCollector.host

The host name that collector announces (the kernel’s host name by default).

Type: string

Default:

config.networking.hostName

Declared by:

services.ccdash-hub.localCollector.user

The user whose collector runs on this machine.

Type: string

Example:

"alice"

Declared by:

services.ccdash-hub.nginx.enable

Whether to enable an nginx virtual host proxying to the hub, WebSocket and server-sent events included. Listening addresses, TLS and access control are yours to add on services.nginx.virtualHosts.<domain> .

Type: boolean

Default:

false

Example:

true

Declared by:

services.ccdash-hub.nginx.domain

The virtual host’s name, also the hub’s public URL.

Type: string

Example:

"ccdash.example.org"

Declared by:

services.ccdash-hub.port

Loopback port of the HTTP API and web UI; put a TLS reverse proxy in front of it (nginx).

Type: 16 bit unsigned integer; between 0 and 65535 (both inclusive)

Default:

7837

Declared by:

services.ccdash-hub.reports.directory

Where the hub keeps the HTML reports sessions publish, as plain files (<workspace>/<slug>.html), outside the database and its nightly copies (backup): put it in a file-level backup of its own.

Type: string

Default:

"/var/lib/ccdash-hub/reports"

Declared by:

services.ccdash-hub.reports.maxMb

The largest report taken, in MiB; also sizes nginx’s body limit on /reports/.

Type: positive integer, meaning >0

Default:

32

Declared by:

services.ccdash-hub.settings

Hub configuration beyond the options here, written to the TOML the daemon reads. Unset keys keep their built-in defaults.

Type: TOML value

Default:

{ }

Example:

{
  workspaces.dirs = [ "~/code/work" ];
  store.retention_days = 90;
  notify.workspaces = [ "work" ];
}

Declared by:

services.ccdash-hub.sync.directory

Where the hub keeps the collectors’ Claude Code state (sessions, rewind checkpoints, plans, tasks, pasted content), as plain files. Not in the nightly database copies (backup): put it in a file-level backup of its own.

Type: string

Default:

"/var/lib/ccdash-hub/claude"

Declared by:

services.ccdash-hub.tokenFile

File holding the bootstrap bearer token of the web UI and API, readable by the ccdash user; null generates one once into /var/lib/ccdash-hub/ui-token. Devices paired through a link (ccdash url --hub) get tokens of their own (Settings › Devices); the hub accepts this one alongside them, so changing it signs out only the devices still on it.

Type: null or string

Default:

null

Example:

"/run/agenix/ccdash-ui-token"

Declared by:

services.ccdash-hub.webPackage

The built panel the hub serves at / (http.web_dir).

Type: package

Default:

ccdash.packages.${system}.ccdash-web

Declared by:

services.ccdash-hub.workspace.enable

Whether to enable the workspace sync: every collector’s workspace root (its repositories and plain directories) kept in step through bare repositories under sync.directory/workspace/, pushed and fetched over git smart HTTP at /git/ with the collector tokens. Adds git to the hub’s closure, the nginx location with unlimited bodies, and a nightly git gc over the repositories (next to the database copy when backup.enable is on) .

Type: boolean

Default:

false

Example:

true

Declared by:

services.ccdash-hub.workspace.gcOnCalendar

When to run git gc over the repositories (systemd.time(7)).

Type: string

Default:

"*-*-* 03:30:00"

Declared by:

services.ccdash-hub.workspaces

The workspaces: top-level directories on the workstations, each holding project directories (repository clones). Memories, issues, documents and reports belong to a workspace and are shared by its sessions; the panel scopes by them. A workspace is named by its entry’s last path component, and an entry is one of:

  • ~/code/work: a directory under each workstation’s home, whatever its user is called;
  • clients, clients/acme: a directory under each workstation’s workspace root (Home Manager services.ccdash.workspace.root, [workspace] root); a machine without a root has none of it;
  • /srv/shared, C:\work: that path, on every machine that has it.

So the machines need neither the same user nor the same layout. The knowledge tools refuse sessions outside every workspace, so set at least one.

Type: list of string

Default:

[ ]

Example:

[
  "~/code/work"
  "clients"
  "/srv/shared"
]

Declared by:

Home Manager module options

homeModules.default (services.ccdash) runs the collector on a workstation and wires Claude Code to it. Generated from the module; keys the options do not cover go into settings (configuration).

services.ccdash.enable

Whether to enable the ccdash collector: reports this machine’s Claude Code sessions to a ccdash hub (the NixOS module services.ccdash-hub) and carries out what the hub sends back .

Type: boolean

Default:

false

Example:

true

Declared by:

services.ccdash.package

The ccdash package.

Type: package

Default:

ccdash.packages.${system}.ccdash

Declared by:

services.ccdash.claudeCode.asks.enable

Whether ccdash can answer prompts: the PermissionRequest hook becomes ccdash ask, which holds each tool approval, question and plan open so the web UI or a notification button can answer it while the terminal dialog stays open. Otherwise the hook only reports the prompt. Needs hooks.enable.

Type: boolean

Default:

true

Declared by:

services.ccdash.claudeCode.attachments.enable

Whether sessions may read the files attached to prompts in the panel without asking: adds a Read rule for the collector’s attachments directory (attachments/ in ccdash’s state directory) to programs.claude-code.settings.permissions.allow. Without it Claude asks before opening each attached file. Sessions the panel starts get the rule through their own settings either way. Set settings.attachments.enable to false to stop this machine fetching attachments at all.

Type: boolean

Default:

true

Declared by:

services.ccdash.claudeCode.channel.enable

Whether to enable replying to sessions from ccdash, through a Claude Code channel. Puts a claude wrapper first in PATH that starts interactive sessions with --channels plugin:ccdash@inline --plugin-dir …; subcommands, -p and --bg run unchanged (sessions started from the panel get the plugin through [launch] command). The wrapper also takes --project <name>, which starts the session under that project of the workspace. Claude Code only loads the channel when it is allowlisted (the NixOS module’s programs.ccdash.channel.allow) or with devFlag .

Type: boolean

Default:

false

Example:

true

Declared by:

services.ccdash.claudeCode.channel.devFlag

Whether to load the channel with --dangerously-load-development-channels instead of --channels. Needs no allowlist, but Claude Code then shows a warning dialog at every launch.

Type: boolean

Default:

false

Declared by:

services.ccdash.claudeCode.daemon.enable

Whether Claude Code’s background supervisor runs as its own user service, instead of being started by the first claude --bg. Started from the panel it would live in the collector’s cgroup and die with every collector restart, taking the background sessions with it, and it would keep the environment of whatever started it. Restarting this service keeps the sessions: the next supervisor adopts them. It starts with default.target, so a host nobody logs in to needs loginctl enable-linger. Needs programs.claude-code.package.

Type: boolean

Default:

true

Declared by:

services.ccdash.claudeCode.hooks.enable

Whether to register the ccdash hooks in programs.claude-code.settings.

Type: boolean

Default:

true

Declared by:

services.ccdash.claudeCode.plugin.enable

Whether every Claude Code session loads the ccdash plugin: the knowledge tools (recall, remember, issue_add, …) and the ccdash:wrap-up, ccdash:report and ccdash:project skills. Installed through programs.claude-code.plugins (Claude Code 2.1.157 or later); sessions with the channel load the same plugin through --plugin-dir, which takes precedence.

Type: boolean

Default:

true

Declared by:

services.ccdash.claudeCode.statusLine.enable

Whether to enable the statusline wrapper that feeds model, context, cost and rate-limit stats to ccdash. Replaces programs.claude-code.settings.statusLine .

Type: boolean

Default:

false

Example:

true

Declared by:

services.ccdash.claudeCode.statusLine.command

Statusline command to run behind the wrapper. null collects the stats without showing a statusline.

Type: null or string

Default:

null

Example:

lib.getExe pkgs.ccstatusline

Declared by:

services.ccdash.claudeCode.telemetry.enable

Whether to enable Claude Code’s OpenTelemetry export to ccdash, for tokens, cache hits, API latency, commits, pull requests and edit decisions in the analytics view. Sets the OTEL_* variables in programs.claude-code.settings.env and a loopback-only receiver in the collector, which forwards the kept records to the hub; prompt text stays redacted .

Type: boolean

Default:

false

Example:

true

Declared by:

services.ccdash.claudeCode.telemetry.port

Loopback port of the OTLP/HTTP receiver.

Type: 16 bit unsigned integer; between 0 and 65535 (both inclusive)

Default:

7839

Declared by:

services.ccdash.dms.enable

Whether to enable the DankMaterialShell plugin: bar pill, popout list, dash tab and card, notifications, and dms ipc call ccdash …. Linked into $XDG_CONFIG_HOME/DankMaterialShell/plugins/ccdash; enable it once in DMS Settings → Plugins and add the widget to a bar .

Type: boolean

Default:

false

Example:

true

Declared by:

services.ccdash.editor

The editor the panel’s Edit in the editor (Ctrl G) opens a draft in, inside terminal. It must return when the file is closed; exit status 0 takes the text, anything else (:cq) cancels. null turns it off; an editor with a window of its own goes in settings.edit.command.

Type: null or string

Default:

null

Example:

"nvim"

Declared by:

services.ccdash.hub.local

Whether to enable a hub on this machine (the NixOS module with services.ccdash-hub.localCollector for this user): url and tokenFile default to it .

Type: boolean

Default:

false

Example:

true

Declared by:

services.ccdash.hub.tokenFile

File holding this machine’s collector token, the one the hub lists under this host name. $VAR and ${VAR} expand. With local the token the hub generated for this machine.

Type: string

Example:

"\${XDG_RUNTIME_DIR}/agenix/ccdash-collector-token"

Declared by:

services.ccdash.hub.url

The hub’s /collect endpoint; with local ws://127.0.0.1:7837/collect (set it for another port).

Type: string

Example:

"wss://ccdash.example.org/collect"

Declared by:

services.ccdash.launch.direnv

Whether sessions started from the panel get the direnv environment of the directory they start in (the variables matching launch.env), through their settings file. claude --bg runs in Claude Code’s background daemon, which never sees the collector’s environment, so this is the only way in. A direnv failure (not allowed, an error) fails the launch.

Type: boolean

Default:

config.programs.direnv.enable

Declared by:

services.ccdash.launch.env

Globs (*, ?) of the direnv variables launched sessions get; nothing passes without a match.

Type: list of string

Default:

[ ]

Example:

[
  "CLAUDE_META_*"
]

Declared by:

services.ccdash.power.lock

Whether to enable locking this machine’s graphical session from the panel (Machines › the machine › Lock, also on its card while the session is unlocked). The collector runs settings.power.lock_command (loginctl lock-session for the user’s display session), which any locker listening to logind answers, DankMaterialShell’s included .

Type: boolean

Default:

false

Example:

true

Declared by:

services.ccdash.power.suspend

Whether to enable suspending this machine from the panel (Machines › the machine › Suspend). The collector hands the hub what is pending of Claude Code’s state, then runs settings.power.suspend_command (systemctl suspend), which logind allows the user of an active seat session. Waking it again needs wake-on-LAN on a wired card and a hub that reaches its network (see the hub’s wake.via) .

Type: boolean

Default:

false

Example:

true

Declared by:

services.ccdash.settings

Collector configuration, written to $XDG_CONFIG_HOME/ccdash/config.toml. Unset keys keep their built-in defaults.

Type: TOML value

Default:

{ }

Example:

{
  niri.terminals = [ "com.mitchellh.ghostty" "foot" ];
  procs.enable = false;
}

Declared by:

services.ccdash.sync.enable

Whether to enable keeping this machine’s Claude Code state (sessions, rewind checkpoints, plans, tasks, pasted content, the prompt history) in step with the hub, so a session ended here resumes on another machine and the prompt history is one. The hub refuses prompts in a session that is open on another machine. Configure what travels under settings.sync (include, exclude, root) .

Type: boolean

Default:

false

Example:

true

Declared by:

services.ccdash.systemdTarget

systemd user target the collector starts with.

Type: string

Default:

"graphical-session.target"

Declared by:

services.ccdash.terminal

The terminal ccdash opens things in on this machine: background sessions (the panel’s Open, ccdash open) and, with editor, drafts. null turns both off; the panel then hides them.

Type: null or (submodule)

Default:

null

Example:

{
  command = [ "ghostty" "-e" ];
  appId = "com.mitchellh.ghostty";
}

Declared by:

services.ccdash.terminal.appId

The terminal’s window app id, so ccdash ties a session to its window on niri (focus, ccdash open). null keeps the built-in list of common terminals.

Type: null or string

Default:

null

Example:

"com.mitchellh.ghostty"

Declared by:

services.ccdash.terminal.command

Opens a new terminal window running the program and arguments that follow.

Type: list of string

Default:

[ ]

Example:

[
  "ghostty"
  "-e"
]

Declared by:

services.ccdash.transcribe.enable

Whether to enable putting recordings into words on this machine with whisper.cpp: the panel’s dictation (the microphone in a message field), and what is said in a recording or a video attached to a prompt, which Claude cannot hear. Everything runs here; nothing leaves the machine. Sets settings.transcribe.command .

Type: boolean

Default:

false

Example:

true

Declared by:

services.ccdash.transcribe.package

The whisper.cpp package; its whisper-cli is run.

Type: package

Default:

pkgs.whisper-cpp

Declared by:

services.ccdash.transcribe.extraArgs

More arguments for whisper-cli, before the file.

Type: list of string

Default:

[ ]

Example:

[
  "--threads"
  "8"
]

Declared by:

services.ccdash.transcribe.language

The language spoken, as whisper names it (en, cs, …); auto lets it tell from the first seconds, which goes wrong more often on a short sentence.

Type: string

Default:

"auto"

Example:

"cs"

Declared by:

services.ccdash.transcribe.model

The model file (ggml). The default is small, 466 MB, many languages: a sentence takes a few seconds on a desktop’s processor. base (142 MB) is faster and worse outside English; medium and large-v3-turbo (1.5 GB each) are better and want a strong machine. Fetch another the same way, with its own hash.

Type: absolute path

Default:

pkgs.fetchurl {
  url = "https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-small.bin";
  hash = "sha256-G+OpsgY4Z7k35k4ux0gzZKeZF+FX+pjF2UtcH//qmHs=";
}

Declared by:

services.ccdash.video.enable

Whether to enable cutting still frames from videos attached to a prompt, which Claude cannot watch: the prompt then names the frames (and, with transcribe.enable, what is said). Sets settings.video.ffmpeg; the number of frames and their size are settings.video.frames (12) and settings.video.edge (1568) .

Type: boolean

Default:

false

Example:

true

Declared by:

services.ccdash.video.package

The ffmpeg package; its ffmpeg and ffprobe are run.

Type: package

Default:

pkgs.ffmpeg-headless

Declared by:

services.ccdash.workspace.enable

Whether to enable keeping this machine’s workspace root (every git repository and plain directory under it, at depth) in step with the other machines through the hub: snapshots of the working tree, the staged state, branches, tags and stashes travel as they change; the other machines fast-forward or merge, conflicts land as git markers plus an entry in the panel. The hub owns the configuration once it has one; the options here are the starting point (handoff’s config.toml carried over). The collector’s unit runs with CPUWeight=20, IOWeight=20 and Nice=10 so a seed or a big merge never competes with your work .

Type: boolean

Default:

false

Example:

true

Declared by:

services.ccdash.workspace.alwaysExclude

Directory names that never travel, wherever they appear, unless syncIgnored names them for a unit.

Type: list of string

Default:

[
  "node_modules"
  ".venv"
  "venv"
  ".direnv"
  ".devenv"
  "target"
  "result"
  "result-*"
  "__pycache__"
  ".cache"
]

Declared by:

services.ccdash.workspace.autoIncludeMb

A new directory at unit depth under this many MB is included by itself; a bigger one waits for a tap in the panel.

Type: unsigned integer, meaning >=0

Default:

500

Declared by:

services.ccdash.workspace.depth

Units are expected this many levels below the root (2: <root>/<bundle>/<repo>).

Type: positive integer, meaning >0

Default:

2

Declared by:

services.ccdash.workspace.exclude

Globs on unit ids that never travel; wins over include.

Type: list of string

Default:

[ ]

Example:

[
  "me/nixpkgs"
  "*_bkp"
]

Declared by:

services.ccdash.workspace.include

Globs on unit ids (<bundle>/<repo>) that travel; empty includes every unit.

Type: list of string

Default:

[ ]

Example:

[
  "work/*"
  "me/*"
]

Declared by:

services.ccdash.workspace.maxFileMb

Untracked files above this many MB are skipped and listed.

Type: positive integer, meaning >0

Default:

64

Declared by:

services.ccdash.workspace.root

The workspace root; ~/ and $VAR expand. The hub’s relative workspaces (work, clients/acme in its workspaces) are directories under it on this machine, with the sync or without; enable needs it.

Type: null or string

Default:

null

Example:

"~/code"

Declared by:

services.ccdash.workspace.syncIgnored

Gitignored files and directories (paths relative to the unit, a glob in the last segment) that travel anyway; paths under .devenv/state are carried only while no local process holds them open.

Type: list of string

Default:

[
  ".env"
  ".env.*"
  ".envrc.local"
]

Declared by:

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.

Data

  1. Where
  2. What the database keeps
  3. Backups and imports

1. Where

On the hub:

WhatWhere (NixOS module)
Live statehub memory, one reducer per host
History/var/lib/ccdash-hub/ccdash.db (SQLite, WAL), ccdash user
Backups/var/lib/ccdash-hub/backups/, nightly, checked
State sync/var/lib/ccdash-hub/claude/, plain files (not in backups)
Catalog/var/lib/ccdash-hub/catalog.db, past sessions read from the synced transcripts
Workspace/var/lib/ccdash-hub/claude/workspace/<unit>.git, bare repos
Reports/var/lib/ccdash-hub/reports/<workspace>/<slug>.html, plain files (not in backups)
Config/etc/ccdash/hub.toml

On each workstation the collector keeps only what it cannot deliver yet:

WhatWhere
Mirrorcollector memory (this machine’s sessions, for DMS and the CLI)
Outbox~/.local/state/ccdash/outbox.ndjson, bounded
Notes~/.local/state/ccdash/notes-cache.json
Sync~/.local/state/ccdash/sync.db (what is in step)
Workspace~/.local/state/ccdash/workspace/ (hidden gitdirs of plain units, temporary indexes, workspace.db, the cached setup)
Config~/.config/ccdash/config.toml
Sockets$XDG_RUNTIME_DIR/ccdash/ (ingest.sock, api.sock)
Telemetry127.0.0.1:7839 (OTLP/HTTP JSON), when enabled

2. What the database keeps

Every row carries the host it came from. Kept for store.retention_days (30 by default):

TableHolds
eventsprompts (up to 8 KiB), task notifications, subagent messages and Claude’s messages and replies (up to 32 KiB), tool calls (name, path or first command line, duration, output up to 8 KiB), permission requests and answers, tasks, subagents, compactions, state changes, resolved marks
samplesonce a minute per session from the statusline: context, cost, limits, model, lines
proc_samplesonce a minute per session: CPU, memory, process count
sessionsid, directory, title, kind, start and end, branch
limit_samplesper-model weekly limits from each /usage poll
telemetrywith telemetry on: API requests (tokens, cost, latency), errors, approvals, commits, edits, active time
session_messagesmessages between sessions and from you

Claims end with their session or their deadline; revoked device tokens go after a while. Not pruned: notes, links, notes_fts (knowledge), live device tokens and their push subscriptions, sync_files, sync_history, sync_conflicts, sync_growth (state sync), workspace_units, workspace_refs, workspace_conflicts, workspace_config, workspace_seen (workspace sync; workspace_events keeps 90 days).

The catalog (catalog.db next to the database, SQLite) is what Sessions › Past searches: a row per transcript the state sync holds (titles, first and last prompt, Claude’s last text, dates, size, numbers, the machines that wrote it) and every prompt and block of Claude’s text (up to 16 KiB each) with a full-text index. It is derived only: the nightly copy leaves it out, deleting it (hub stopped) rebuilds it from the transcripts, and a new version of what it extracts rebuilds it by itself. Nothing is pruned; a transcript that grows is read from where it stopped, one replaced is read again.

3. Backups and imports

ccdash backup --config /etc/ccdash/hub.toml copy.db   # what the nightly timer runs
ccdash import db old.db --config /etc/ccdash/hub.toml # history of a pre-hub daemon, safe to repeat

The nightly copy goes through SQLite’s backup API and is checked with PRAGMA integrity_check; backup.keep copies are kept. Delete the database to start over.

Security

Anyone holding a panel token can read your sessions, answer their prompts, start and stop sessions in your projects and, with the channel, prompt them. They can also lock or suspend the machines that allow it (power.lock, power.suspend) and wake machines over the LAN. Treat a token like an SSH key and keep the hub on your LAN or VPN.

  1. Tokens
  2. Pairing a device
  3. What reaches the hub

1. Tokens

TokenHeld byChecked as
bootstraptokenFile on the hubcompared in constant time
deviceeach paired browserrandom, stored as SHA-256, revocable
collectoreach workstation (collectors)names the machine; only /collect, /sync/, /git/, the report upload and the attachment fetch take it
notification keyone prompt’s buttonsrandom, dies with the prompt
view linkone report’s frameHMAC-signed, an hour, key drawn at start (reports)
attachment linkone attached fileHMAC-signed, six hours, key drawn at start

Rotating tokenFile (and restarting the hub) signs out only the devices still on the bootstrap token.

2. Pairing a device

sudo -u ccdash ccdash url --hub --config /etc/ccdash/hub.toml --qr

or “Connect a phone” in Settings on a paired browser. Every link carries a token minted for that one device: good for an hour until the link is opened, then for as long as the device keeps it.

Settings › Devices lists them with their browser and last use; rename one with its pencil, or revoke it to sign it out at its next request and end its push notifications. A device still on the bootstrap token sees “shared token” there and can take one of its own.

3. What reaches the hub

  • The API under /api/v1 needs a bearer token for everything.
  • /act/<key>/<action> takes a notification button’s one-time key; the access token never goes into a notification.
  • /collect and /sync/ take a collector’s token; /sync/ paths are checked to stay inside the synced directories.
  • /reports/-/upload takes a collector’s token; /reports/-/view/<key> takes a signed view link and serves the report as a sandboxed, opaque origin that loads nothing from the network, so a report’s scripts never see the panel’s token (reports).
  • /attachments/-/fetch/<id> takes a collector’s token; /attachments/-/view/<key> takes a signed link and serves the file with its kind read from its bytes, nosniff and a sandboxing policy: pictures, recordings and PDFs show in place, everything else is a download, so an uploaded page or SVG never runs in the panel’s origin. File names are reduced to letters, digits, ., _ and - before they reach a disk or a prompt. On a workstation the fetched files are the owner’s alone (0600 under a 0700 directory).
  • The OpenTelemetry receiver on a workstation takes no token, so the collector binds it to loopback only.
  • Lock and suspend reach only a machine whose collector has power.lock or power.suspend on; the collector checks that again itself. Magic packets go only to the broadcast address of a network the hub is on, or to a wake.via address in the hub’s own configuration (machines).
  • Nothing leaves the hub except Web Push to subscribed devices, encrypted for the device: the push service sees only ciphertext.
  • The hub keeps the synced ~/.claude as plain files: put its directory in an encrypted backup (state sync).

Development

  1. The daemons
  2. The panel
  3. Checks
  4. The demo

1. The daemons

direnv allow                                     # or: nix develop
cargo run -- hub --config hub.toml               # http.listen, collect.tokens, store.path
cargo run -- collector --config collector.toml   # hub.url = "ws://127.0.0.1:7837/collect"
  • CCDASH_RUNTIME_DIR (sockets) and XDG_STATE_HOME (outbox, sync index) give a second collector, or the hooks of a test session, a place next to the real one.
  • CCDASH_LOG=info,ccdash=debug for more log.
  • A dev hub with a dummy bootstrap token (devtoken-not-secret) on 127.0.0.1 is the usual end-to-end setup; feed it hook payloads with printf '{…}' | CCDASH_RUNTIME_DIR=… ccdash emit.

2. The panel

web/ is SvelteKit with Svelte 5, Tailwind, shadcn-svelte and LayerChart; Node and npm are in the devshell.

cd web && npm ci
npm run dev                   # Vite on :5173; /api and /act go to CCDASH_HUB (127.0.0.1:7837)
npm run check && npm run lint
npm run build                 # → web/build, what a `cargo run` hub serves
  • The hub serves http.web_dir (the Nix build bakes in the ccdash-web package; a cargo run hub falls back to web/build; CCDASH_WEB_DIR overrides both), with index.html for every route.
  • The API’s TypeScript types (web/src/lib/api/types.ts) are generated from the Rust models: cargo test api fails while the file is stale, CCDASH_UPDATE_TYPES=1 cargo test api rewrites it.
  • After a change to web/package-lock.json, put the hash that prefetch-npm-deps web/package-lock.json prints into flake-parts/pkgs/ccdash-web.nix.
  • The service worker only registers in the built app, so push and the offline shell are checked against web/build served by a hub.

3. Checks

cargo test && cargo clippy --all-targets -- -D warnings && cargo fmt --check
cd web && npm run check && npm run lint
nix flake check     # also runs the pre-commit hooks (editorconfig, markdownlint, typos, …)
                    # and the VM tests
nix build .#ccdash .#ccdash-web .#ccdash-aarch64-linux
nix build .#checks.x86_64-linux.vm-single-node -L    # one VM test, with its log

The VM tests (flake-parts/checks/) boot NixOS with the modules as a user would set them up, a stand-in claude answering the collector: vm-single-node is one machine as hub and workstation (localCollector, hub.local), covering the generated tokens, the link and its feature report, the panel, the plugin, the knowledge tools in and outside a workspace, and a hub restart. They need KVM; home-manager is a flake input for them only.

nix flake check sees only files git knows; check a fresh clone or a copy before pushing new files.

Windows. None of the above builds the cfg(windows) half of the crate (a Windows workstation). The windows workflow (.github/workflows/windows.yml) lints and tests it on GitHub with both Windows toolchains, on every push and pull request that touches the crate. From the dev shell, a cross cargo check type-checks it without a Windows machine (it runs nothing):

nix build --impure -o target/win-toolchain --expr 'let f = builtins.getFlake "github:nix-community/fenix"; p = f.packages.x86_64-linux; in p.combine [ p.stable.cargo p.stable.rustc p.targets.x86_64-pc-windows-gnu.stable.rust-std ]'
nix shell nixpkgs#pkgsCross.mingwW64.stdenv.cc -c sh -c \
  'PATH="$PWD/target/win-toolchain/bin:$PATH" CARGO_TARGET_DIR=target/windows cargo check --target x86_64-pc-windows-gnu --all-targets'

Code that touches the operating system goes through what both sides share, so it builds on Windows too:

ForUse
file modes (0700, 0600)fsx::set_mode, fsx::ModeExt
the collector’s socketsipc
starting a programutil::program, util::output_within
the home directory, ccdash’s ownpaths
comparing directories and cwdsworkspace::path_key
what only Linux has#[cfg(unix)], also on tests that drive sh

4. The demo

nix run .#demo                               # or: cargo run -- demo
nix run .#demo -- --listen 127.0.0.1:7841 --dir /tmp/ccdash-demo-2

ccdash demo writes a fresh database (--dir, by default a ccdash-demo temporary directory, emptied only when an earlier demo made it) and serves it at http://127.0.0.1:7840/#token=demo:

  • a week of sessions on two made-up machines, desk and laptop, in two workspaces, acme and personal, written through the hub’s own reducer, so the chats, History and Analytics read as they would for real ones;
  • memories, issues, progress, documents and a report;
  • while it runs, two stand-in collectors keep four sessions open (working, waiting on a permission prompt, the owner’s turn) and report the machines’ numbers, the hub’s own included, all made up.

The content is src/demo/script.rs. Screenshots come from the demo, never from a real hub.

Viewports

web/scripts/viewports.mjs opens the main pages of a running demo at the sizes the panel is used at (two phones, a phone on its side, a tablet, a laptop, a 4K desktop at 150 %), writes a screenshot of each and fails when a page is wider than its screen, a button runs off the edge, the composer’s buttons take more than one row, the chat keeps under 40 % of a session page, or a page throws. Run it after any change to the layout, the composer or the sizes, and look at the phone screenshots: the checks catch what overflows, not what merely looks crowded.

cargo run -- demo &
export PLAYWRIGHT_CORE=$(nix build nixpkgs#playwright-driver --no-link --print-out-paths)
export PLAYWRIGHT_BROWSERS_PATH=$(nix build nixpkgs#playwright-driver.browsers --no-link --print-out-paths)
node web/scripts/viewports.mjs --out /tmp/ccdash-viewports
node web/scripts/viewports.mjs --only phone-small,phone   # some of them

The demo serves web/build, so npm run build first. A phone here is a screen whose short side is under 600 CSS pixels: that is what the Auto text size goes by (prefs.svelte.ts).

Screenshots

docs/images/, taken through a headless browser (Playwright) on the demo with the light colour scheme unless named -dark, at CSS pixel scale, then oxipng -o 4 --strip safe; each under 150 kB. Reload after switching the colour scheme, and wait for a page’s data (Projects and a report’s frame take a few seconds) before shooting.

FilePageViewport
now.png/ (after “Recent progress” shows)1280×800
now-dark.png/, dark1280×800
session.png/sessions/5f1c2a90-… (the checkout session), its 2nd group open1280×1000
projects.png/projects1280×800
history.png/history?range=1h1280×800
analytics.png/analytics/overview?range=7d1280×800
machines.png/machines1280×500
report.png/reports/acme/dependency-audit--2026-111280×800
phone.png/390×844