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
- Look around first:
nix run github:tsandrini/ccdash#demoserves the panel on a made-up workspace at http://127.0.0.1:7840/#token=demo. - Installation: one machine, or a hub and your workstations, then your phone. A workstation can also run Windows.
- Getting started: workspaces, the knowledge tools and skills, a first session from the phone.
- Troubleshooting when a machine does not show up.
The guides
| Page | About |
|---|---|
| The panel | every page of the panel and the desktop plugin |
| Prompts and notifications | answering prompts, Web Push, the channel, renaming |
| Sessions | start, resume, resolve, kill, open, forget |
| Knowledge | notes, tools, injections, import and export |
| Reports | HTML reports: the skill, publishing, the viewer, storage |
| Machines | uptime and basic numbers, lock, suspend, wake-on-LAN |
| State sync | ~/.claude on every machine, the one-machine rule, conflicts |
| Workspace sync | the workspace root on every machine |
| Configuration | every key, and the module options |
| Architecture | components, protocol, the Claude Code interfaces used |
| Data | what is stored where, retention, backups |
| Security | tokens, devices, what can reach the hub |
| Development | building, 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.
- Before you start
- The flake input
- One machine
- A hub and workstations
- Tokens
- Your phone
- Optional features
- Updating
1. Before you start
-
NixOS with flakes, and Home Manager (as a NixOS module or standalone) with
programs.claude-codeenabled. -
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 withoutprograms.claude-code.pluginsbuilds with a warning, and only sessions with the channel get them. -
To look around first:
nix run github:tsandrini/ccdash#demoserves 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
tokenFileunset 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
ccdashuser, 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 mode0400. - One machine (section 3) needs none of this:
localCollectorgenerates 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.
| Feature | Turn on | More |
|---|---|---|
| Replies from the panel (the channel) | HM claudeCode.channel.enable, NixOS programs.ccdash.channel.allow | prompts |
| Open a background session, edit a prompt in your editor | HM terminal ({ command = [ "ghostty" "-e" ]; appId = …; }) and editor | sessions |
| Sessions and prompt history on every machine | HM sync.enable | state sync |
| The workspace root on every machine | hub workspace.enable, HM workspace.enable and workspace.root | workspace sync |
| Lock and suspend from the panel | HM power.lock, power.suspend | machines |
| Model, context, cost and limits per session | HM claudeCode.statusLine.enable | panel |
| Tokens, cache hits, commits in Analytics | HM claudeCode.telemetry.enable | panel |
| The DankMaterialShell bar pill and dash tab | HM dms.enable | panel |
| A nightly database copy | hub backup.enable | data |
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
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.exein~\.local\bin, which joins yourPATH;- the ccdash plugin in
~\.local\share\ccdash\claude-plugin, linked into~\.claude\skills\ccdash: every session gets the knowledge tools and theccdash:wrap-up,ccdash:reportandccdash:projectskills; - 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 assettings.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.
| Feature | Switch | Sets |
|---|---|---|
| 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 | -StatusLine | ccdash 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
| What | Where |
|---|---|
| config | %APPDATA%\ccdash\config.toml |
| state | %LOCALAPPDATA%\ccdash\state (outbox, sync index, notes cache, fetched attachments, the log) |
| runtime | %LOCALAPPDATA%\ccdash\run (pending titles) |
| sockets | named 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
| Area | On Windows |
|---|---|
| the hub, the demo | refused: they run on Linux only |
| stop a session | Claude Code’s tree ends at once (TerminateProcess), no SessionEnd hook; its console is then reset |
| interrupt | the running Bash call’s process tree is ended at once |
| open | no window focus; a background session is attached in a console of its own |
| editor | in a console of its own; Windows Terminal keeps the tab open after a non-zero exit (:cq) |
| machine | no load average (reads 0) or CPU temperature; wake-on-LAN: the card is armed (powercfg, 10 min) |
| lock, suspend | LockWorkStation; SetSuspendState from a hidden PowerShell (sleep, not hibernation) |
| state sync | ReadDirectoryChangesW instead of inotify |
| workspace sync | one recursive watch on the root; no open-file check for quiescence; git dirs outside a unit unwatched |
| network shares | not watched (no extended change records): a root on one is swept every 30 min |
npm’s claude.cmd | runs, 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).
- A first session
- Workspaces and projects
- The knowledge tools and skills
- Bringing in what you have
- From the phone
- 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:
| Entry | The directory on a machine |
|---|---|
~/code | under its user’s home: /home/me/code, C:\Users\me\code |
work, clients/acme | under its workspace root: services.ccdash.workspace.root, [workspace] root |
/srv/code, C:\code | that 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 shopin the session, orclaude --project shopto start one (the channel’sclaudewrapper 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):
| Tools | For |
|---|---|
recall | search the notes, or read one in full |
remember, verify | keep a fact, confirm one still holds |
issue_add, issue_update | open work, with a status and a priority |
progress | a dated entry: what landed, what was decided |
doc_write | plans, specs, anything long |
report_publish | an HTML report, kept on the hub |
claim, release | tell the other sessions what this one works on |
tell_session | a message to another running session |
| Skill | Does |
|---|---|
/ccdash:wrap-up | records what the session learned and did, then lets it close (Resolved) |
/ccdash:report | writes a report in the shared design and publishes it |
/ccdash:project | places 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.
- A machine does not show up
- The knowledge tools refuse
- A session has no ccdash tools or skills
- A button is missing
- No notifications
- 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 says | Because |
|---|---|
connecting: HTTP error: 401 Unauthorized | the 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 laptop | the 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 16 | the hub and this collector are different releases: update both (installation) |
connecting: … Connection refused | the 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 listshould showccdash@skills-dir.- The plugin needs
claudeCode.plugin.enable(the default), Claude Code 2.1.157 or later, and a Home Manager withprograms.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 --resumeit.
4. A button is missing
The panel offers only what the machine does.
| Missing | Turn on |
|---|---|
| Reply, Resolved | the channel: claudeCode.channel.enable and programs.ccdash.channel.allow; restart the session |
| Open, Edit in the editor | services.ccdash.terminal and editor |
| Start a session (no machine) | a connected collector with Claude Code (launch.command) |
| Lock, Suspend | power.lock, power.suspend |
| The Claude state, Workspace pages | sync.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.
- Now and Sessions
- A session’s page
- Projects
- History and Analytics
- Machines, Claude state and Workspace
- Themes
- 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
| Tab | Shows |
|---|---|
| Chat | the exchanges with Claude’s text, its steps, subagents, task notifications, subagent messages, messages between sessions |
| Shell | its Bash calls as a terminal transcript with their output |
| Details | the 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.Enteror a tap uses it instead of the text (undo brings the draft back),Shift Enterinserts 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:
| Keys | Does |
|---|---|
Ctrl Enter | Send (Enter is a new line) |
Ctrl Shift Enter | Next prompt instead of a turn |
Ctrl Shift 1–9 | That quick reply |
Ctrl . | Stop the turn |
Ctrl G | Edit in the editor on a machine (below) |
Ctrl Shift F | Expand the field, and back |
Ctrl Shift D | Dictate; again to finish |
Ctrl J | Go to the open question |
Ctrl ↑ Ctrl ↓ | Walk the prompt history |
Ctrl R | Search the prompt history |
Ctrl B Ctrl I | Bold, italic (with vim keys: in insert mode) |
Ctrl E | Code block around the selection |
Ctrl P | Preview |
Esc, then i | Leave the field (vim: normal mode), come back |
? | Every key, outside a field |
Ctrl K | Search 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,nsteps 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. 0fits 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:
| Section | Answers |
|---|---|
| Overview | daily activity, when you prompt (weekday × hour), work per prompt, cost, lines changed, CPU and memory per project |
| Waits | how long sessions waited on you and how fast you replied, apart from parked time |
| Parallel | how many sessions worked or waited at once; time everything waited with nothing working |
| Limits | 5-hour, 7-day and per-model weekly limits, their pace, each workspace’s share |
| Projects | time, prompts, cost, lines, tool calls, compactions and CPU per directory |
| Turns | what fills a turn, the slowest tools and commands, the commands that fail most |
| Context | compactions and how full sessions got |
| Tokens | tokens by type, cache hits, API latency, commits, edits by language (needs telemetry) |
| Permissions | what 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 first | Otherwise |
|---|---|
DankMaterialShell/dms-colors.json | wal/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
Tool approvals, questions (AskUserQuestion) and plans (ExitPlanMode)
show up in the panel while the terminal dialog stays open; whichever answer
comes first wins.
| Prompt | Answers |
|---|---|
| Tool call | Allow, Deny, Always allow (when Claude Code suggests a rule), Deny with a note |
| Question | one button per option (several for multi-select), or your own text |
| Plan | Approve, 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 loopbackhttpendpoint (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 = trueloads 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
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,↑ ↓(orj k) move,Enterresume,Escclose.
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, how | What runs | Session |
|---|---|---|
| its job is on that machine, nothing changed | claude --bg --resume <id> -- <prompt> | the same one, same options |
| another machine, another model or mode, or its settings file is gone | the command of Start | a 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 close | Then |
|---|---|
| Keep open (Actions), or you type on | the 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 restarts | the 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 is | What happens |
|---|---|
| waiting on a permission prompt | the prompt is denied with Claude Code’s stop; the turn ends at once |
| about to call a tool | the PreToolUse hook denies the call and ends the turn (continue: false) |
| running a Bash command | the command is ended, as Esc does; Claude is told why and ends the turn in a line |
| running another tool | it runs to its end; the PostToolUse hook then ends the turn |
| writing text, no tool call ahead | the turn ends by itself; the interrupt is dropped with it |
| run by hooks older than ccdash | the 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.
| Session | What Kill does |
|---|---|
| Interactive | SIGTERM 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 |
| Background | claude 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), asccdash opendoes. - 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:
state | Claude Code means | ccdash shows |
|---|---|---|
working | a turn is running | Working |
blocked | it needs something from you | your turn, then parked |
done | finished what you asked, ready for the next prompt | your turn, then parked |
failed, stopped | it ended | ended, 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.
- Attaching
- What Claude gets
- Photos are made smaller
- Files: what is kept, and for how long
- How it works
- Turning it off, and the bounds
- Dictation
- Recordings and videos
- 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]
| Kind | What Claude does with it |
|---|---|
| picture (JPEG, PNG, GIF, WebP) | sees it, by reading the file |
| PDF, text, code | reads it |
| sound, video | cannot hear or watch: it gets the words and still frames (below) |
| anything else | opens 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 underattachments.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):
| Key | Default | Is |
|---|---|---|
enable | true | off: no attaching in the panel, no Files area |
dir | attachments/ next to the database | where the files are |
max_image_mb | 25 | the largest picture |
max_audio_mb | 50 | the largest sound recording |
max_video_mb | 300 | the largest video |
max_file_mb | 50 | the largest file of another kind |
quota_mb | 5120 | all files together; 0: no quota |
retention_days | 30 | when 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):
| Key | Default | Is |
|---|---|---|
enable | true | off: this machine fetches nothing, the panel says so |
dir | attachments/ in ccdash’s state directory | where fetched files go |
keep_days | 7 | a 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.
| Key | Default | Is |
|---|---|---|
transcribe.command | [] (off) | prints what is said in {file} |
transcribe.timeout_secs | 300 | the command is stopped after this long |
transcribe.attachments | true | attached recordings and videos get their words too |
video.ffmpeg | "" (off) | the ffmpeg to cut frames with (ffprobe beside it) |
video.frames, .edge | 12, 1568 | how many frames, and their longest side in pixels |
video.timeout_secs | 300 | cutting 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
| Kind | For |
|---|---|
| memory | facts worth keeping |
| issue | open work, with a status |
| progress | dated entries |
| doc | plans, specs, anything long |
| report | an 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 emptyprojectonrememberorissue_updatemakes a note workspace-wide. - A session’s project is the launch’s (the panel), or
claude --project <name>in a terminal (which setsCCDASH_PROJECT; thechannelwrapper takes the flag), else the one itclaims withproject,/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; claimpathsresolve 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 andclaude --projectplace 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_writecarries 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:
| When | What | Switch |
|---|---|---|
| session start | open issues, relevant memories, documents, reports, recent progress | inject.session_start |
| every prompt | other sessions active in the project, messages for it | inject.prompt |
| before editing a file | who else edited it lately, claims covering it | inject.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
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:
| Argument | Meaning |
|---|---|
path | the HTML file on the session’s machine (absolute, or relative to the session’s directory) |
title | default: the file’s <title> |
slug | default: from the title; publishing to an existing slug replaces that report (the note’s version grows) |
summary | one line for lists |
body | the abstract, markdown; [[slug]] links as in any note |
project | default: the session’s project |
date | YYYY-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/-/uploadtakes a collector’s token only.- The panel never gets the file’s address with its token: it asks
POST /api/v1/reports/{ws}/{slug}/viewfor 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 underContent-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 ownsandboxwithoutallow-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
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.
| Field | Source |
|---|---|
| up, slept | CLOCK_BOOTTIME (sleep included), minus CLOCK_MONOTONIC (sleep excluded) for time slept |
| awake since | the last resume the collector saw: the gap between the two clocks grew |
| CPU | busy share since the last reading (/proc/stat), load average, cores |
| temperature | k10temp Tctl, zenpower Tdie, coretemp package, cpu_thermal, the first found |
| memory | total minus available, swap used (/proc/meminfo) |
| disks | statvfs of / and $HOME (the hub: / and its database’s directory), one per device |
| battery | the first power_supply of type Battery that is not a device’s (a mouse), mains online |
| system | PRETTY_NAME, the kernel, reboot pending (NixOS: the booted and current systems differ) |
| network | physical wired cards: MAC, IPv4 addresses, whether power/wakeup is on (wake-on-LAN) |
| screen | logind’s LockedHint of the user’s display session, which the screen locker sets |
| can suspend | the 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 settingsand the firewall. Setwake.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
| State | Shown as | Ends |
|---|---|---|
| connected | green, “connected for …” | the link drops |
| asleep | amber, “asleep since …” (suspended here) | the machine connects again, or reports again 15 s later |
| waking | amber, “waking for …” | it connects; after 3 min the panel offers Wake again |
| offline | red, “offline for …”, the last report faded | it 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
| Where | Key | Default | Meaning |
|---|---|---|---|
| collector | power.lock | false | carry out the panel’s Lock |
| collector | power.lock_command | ["loginctl", "lock-session", "{session}"] | locks; {session} is the display session’s id |
| collector | power.suspend | false | carry out the panel’s Suspend |
| collector | power.suspend_command | ["systemctl", "suspend"] | suspends; must return once the sleep is on its way |
| hub | wake.via.<host> | — | ip or ip:port the packets go to when no network is shared |
| Home Manager | services.ccdash.power.lock | false | sets power.lock |
| Home Manager | services.ccdash.power.suspend | false | sets 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).
- Turning it on
- What travels
- How files travel
- One session, one machine
- Conflicts
- The State page
- 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>.
| Action | Effect |
|---|---|
| Keep the current version | the machine deletes its copy |
| Use the copy | the copy replaces the version on every machine; the replaced one becomes the copy, so the choice can be undone |
| Hide | the 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.
- Turning it on
- Units
- How a change travels
- What stays home
- Conflicts, held snapshots, diverged branches
- A new machine, an existing copy
- The Workspace area
- On the hub
- 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:
| Unit | Example | How |
|---|---|---|
a repository at unit depth (<bundle>/<repo>) | tsandrini/ccdash | its own .git |
| a bundle root that is a repository | tsandrini (with .claude/, meta/) | the same; the directories that are units of their own are left out of its tree by pathspec |
| a repository nested deeper | meteopress/livance/nested | its own unit; the parent leaves the directory alone (an existing gitlink stays as it is) |
| a plain directory at unit depth | meteopress/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 -Ainto it (plusgit add -ffor the opted-in ignored paths, with the directories of nested units and untracked files overmax_file_mbexcluded by pathspec) gives the work tree;write-treeon 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/*: whatgit statuscompares 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 underrefs/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: fetchrefs/sync/<other>asS,merge-base L S.Salready in → nothing.Lis the base → fast-forward:read-tree -u -mmoves the working tree toS’s, the index becomesS’s staged state, HEAD and the branches follow,refs/sync/<me>becomesS. Otherwise merge:merge-tree --write-treeof 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 becomesrefs/sync/<me>, pushed so the other side fast-forwards.read-tree -u -mrefuses 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 nextgit fetchsettles 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/configtravels. A remote whose URL holds a password or a token (https://user:token@…, or any user in anhttp(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 withccdash 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 heldconfig.lockduring 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. Anode_modulescan 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 anysync_ignoredentry): 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/*andrefs/sync-tips/*are visible ingit log --allandfor-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 chooseset_asideinstead: 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:
maincommitted on two hosts within one window. The local branch stays, the other tip isrefs/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 initdoes the same now andccdash workspace statusfollows 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 hubmakes this copy exactly the hub’s content (its own branch tips are kept underrefs/sync/diverged/<this machine>/…when they are not behind),--prefer minemakes 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)
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
| Key | Default | Meaning |
|---|---|---|
host | the kernel’s host name | the name the panel shows for the hub |
http.listen | ["127.0.0.1:7837"] | addresses of the API and the panel |
http.token_file | generated in the state dir | the bootstrap token |
http.public_url | LAN address and first port | where phones open the panel (links, pairing) |
http.web_dir | the built panel | the panel’s files |
collect.tokens | {} | host name → collector token file |
store.path | <state dir>/ccdash.db | the database |
store.retention_days | 30 | history kept |
store.tool_output_bytes | 8192 | Bash 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_secs | 15, 120 | how long a prompt waits before it notifies |
notify.permissions, .questions, .plans, .turns | true | what notifies |
notify.workspaces | [] (all) | only these workspaces notify |
notify.web_url | http.public_url | where notification taps lead |
push.enabled | true | Web Push |
push.subject, .ttl_secs, .key_file | public URL, 3600, state dir | VAPID contact, message lifetime, key pair |
knowledge.reflect | true | the daily staleness pass |
knowledge.stale_unverified_days, .stale_unrecalled_days | 90, 60 | when memories turn stale |
sync.dir | claude/ next to the database | the synced files |
workspace.enable | false | the workspace sync (repositories under sync.dir/workspace) |
reports.dir | reports/ next to the database | the published reports’ HTML files |
reports.max_mb | 32 | the largest report taken |
attachments.enable, .dir | true, attachments/ next to the database | files attached to prompts (attachments) |
attachments.max_image_mb, .max_audio_mb, .max_video_mb, .max_file_mb | 25, 50, 300, 50 | the largest file taken, by kind |
attachments.quota_mb, .retention_days | 5120, 30 | all 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
| Key | Default | Meaning |
|---|---|---|
host | the kernel’s host name | must 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"], 5 | the liveness poll |
usage.command, .interval_secs | ["claude"], 600 | the /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.channel | false | launched sessions load the ccdash channel (--channels) |
launch.stop, .remove | claude 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_days | true, attachments/ in the state directory, 7 | fetches a prompt’s attached files for this machine’s sessions; days an unused one stays |
transcribe.command, .timeout_secs, .attachments | [] (off), 300, true | puts recordings into words: dictation, and attached recordings and videos (attachments) |
video.ffmpeg, .frames, .edge, .timeout_secs | "" (off), 12, 1568, 300 | cuts still frames from attached videos (attachments) |
niri.enable, .terminals | true, common terminals’ app ids | window focus and which windows are terminals |
procs.enable, .interval_secs | true, 5 | CPU and memory sampling |
telemetry.listen | [] | OTLP receiver (loopback only) |
queue.max_bytes | 32 MiB | the outbox while the hub is unreachable |
inject.session_start, .prompt, .edits | true | the knowledge injections |
sync.enable | false | the state sync |
sync.root | $CLAUDE_CONFIG_DIR, else ~/.claude | what is kept in step |
sync.include, .exclude | see state sync | what travels |
sync.interval_secs | 3 | full scans, only without inotify |
workspace.enable, .root | false, — | the workspace sync and its root (~/ and $VAR expand); the hub’s relative workspaces are under the root, sync or not |
workspace.depth | 2 | units at <root>/<bundle>/<repo> |
workspace.include, .exclude | [], [] | globs on unit ids; the starting configuration a hub without one takes |
workspace.always_exclude | see workspace | directory 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_mb | 64, 500 | the untracked file cap, the new-directory threshold |
power.suspend | false | carry out the panel’s Suspend |
power.suspend_command | ["systemctl", "suspend"] | suspends; returns once the sleep is on its way |
power.lock | false | carry 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 Managerservices.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
on each workstation on the hub (always on)
Claude Code hooks ──► ccdash emit ─┐
prompts ────────────► ccdash ask ──┤
statusline ─────────► ccdash tee ──┼──► ccdash collector ══wss══► ccdash hub
claude agents --json ──────────────┤ │ (forwards, acts, │ (state, SQLite,
claude -p /usage ──────────────────┤ │ syncs ~/.claude) │ notifications)
niri window events ────────────────┘ └──► DMS plugin ├──► web panel
└──► Web Push
| Part | Runs | Does |
|---|---|---|
ccdash emit, ask, tee | as Claude Code hooks and the statusline | hand each payload to the local collector; never fail Claude Code |
ccdash collector | a user service per machine | forwards to the hub, carries out what comes back, syncs ~/.claude |
ccdash hub | a system service, one per setup | keeps live state and history, serves the panel and the API, sends Web Push |
ccdash channel | an MCP server per session | delivers replies from the panel; exposes the knowledge tools |
ccdash report | the CLI | builds a report in the shared chrome; publishes one through the collector |
| DMS plugin | in DankMaterialShell | this machine’s sessions in the bar and the dash |
2. What Claude Code interfaces are used
Public ones only: claude agents --json, claude --bg, claude stop,
claude rm, claude attach, claude daemon run, hooks, the statusline payload,
channels,
OpenTelemetry and the
/usage report.
The one exception is the state sync: it copies the files
Claude Code keeps under ~/.claude byte for byte and reads only the
running-session registry (sessions/<pid>.json) and the prompt history’s
lines; the transcript format is never parsed.
3. The collector
- Takes hook events over a Unix datagram socket and forwards them to the
hub over one WebSocket (
/collect, a token per machine). While the hub is unreachable, events wait in an on-disk queue and Claude Code runs as if ccdash were not there. - Polls
claude agents --json --allevery 5 s for liveness and background sessions, andclaude -p /usageevery 10 minutes for the per-model weekly limits the statusline lacks (safe mode: no model request, no hooks, nothing saved; about a second of CPU). - Reads which skills Claude Code loads on the machine (the user’s, the
plugins’, each workspace’s) every five minutes and tells the hub when
they change, for the composer’s
/menu. - Reads each session’s git branch from
.git/HEAD(worktrees included) without running git, and its process tree’s CPU and memory (PSS) from/procevery 5 s. - Reports its machine every 30 s (uptime, CPU, memory, disks, battery, its wired cards for wake-on-LAN) and reconnects at once after a long sleep (machines).
- Carries out what the hub sends: replies, prompt answers, renames, sessions to start, stop or open, sync work.
- Serves a local API (
$XDG_RUNTIME_DIR/ccdash/api.sock) for the hooks, the CLI and the DMS plugin, with a mirror of this machine’s sessions.
Claude Code reads hooks when a session starts: sessions that were running before ccdash was installed only show busy and idle until they are resumed.
The hooks answer Claude Code, too: a queued title, the knowledge the hub injects at a session start or prompt, the one-machine guard, and the stop of a turn interrupted from the panel: every main-thread tool hook asks the collector (one local round trip, in memory) whether an interrupt is pending and, if so, ends the turn (sessions).
4. The hub
- One reducer per host turns events and polls into live session state; the history goes to SQLite (data).
- Serves the panel (
web/, built into theccdash-webpackage) and the HTTP API under/api/v1, with server-sent events for live updates. - Sends Web Push for prompts and finished turns, with answer buttons.
- Keeps the synced
~/.claudefiles and the knowledge notes, and reads the synced transcripts into a searchable catalog of past sessions (src/catalog/, its owncatalog.db), which is what Sessions › Past and resuming a session the store never saw run use. - Keeps every node’s last report across restarts, reads its own machine, and sends wake-on-LAN magic packets (machines).
A conversation in the panel is rebuilt from hook events, so Claude’s thinking is not part of it.
5. Protocol
Collector and hub speak JSON messages over the WebSocket
(src/protocol.rs). The protocol is versioned: a hub and a collector of
different versions refuse each other and log why, so a hub and its
collectors are upgraded together. The state sync uses plain HTTP routes
under /sync/ with the collector’s token; the workspace sync uses git
smart HTTP under /git/ with the same token (git http-backend behind
the hub) and carries its configuration, unit states and conflict
resolutions over the WebSocket (protocol 8). The collectors’ skill reports
came with protocol 11, the desktop’s colours with protocol 12, the
machine’s report, lock and suspend with protocol 13, the report note
kind with protocol 14, drafts opened in an editor on a machine with
protocol 15.
Data
1. Where
On the hub:
| What | Where (NixOS module) |
|---|---|
| Live state | hub 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:
| What | Where |
|---|---|
| Mirror | collector 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) |
| Telemetry | 127.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):
| Table | Holds |
|---|---|
events | prompts (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 |
samples | once a minute per session from the statusline: context, cost, limits, model, lines |
proc_samples | once a minute per session: CPU, memory, process count |
sessions | id, directory, title, kind, start and end, branch |
limit_samples | per-model weekly limits from each /usage poll |
telemetry | with telemetry on: API requests (tokens, cost, latency), errors, approvals, commits, edits, active time |
session_messages | messages 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
| Token | Held by | Checked as |
|---|---|---|
| bootstrap | tokenFile on the hub | compared in constant time |
| device | each paired browser | random, stored as SHA-256, revocable |
| collector | each workstation (collectors) | names the machine; only /collect, /sync/, /git/, the report upload and the attachment fetch take it |
| notification key | one prompt’s buttons | random, dies with the prompt |
| view link | one report’s frame | HMAC-signed, an hour, key drawn at start (reports) |
| attachment link | one attached file | HMAC-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/v1needs a bearer token for everything. /act/<key>/<action>takes a notification button’s one-time key; the access token never goes into a notification./collectand/sync/take a collector’s token;/sync/paths are checked to stay inside the synced directories./reports/-/uploadtakes 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,nosniffand 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.lockorpower.suspendon; the collector checks that again itself. Magic packets go only to the broadcast address of a network the hub is on, or to awake.viaaddress 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
~/.claudeas plain files: put its directory in an encrypted backup (state sync).
Development
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) andXDG_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=debugfor more log.- A dev hub with a dummy bootstrap token (
devtoken-not-secret) on127.0.0.1is the usual end-to-end setup; feed it hook payloads withprintf '{…}' | 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 theccdash-webpackage; acargo runhub falls back toweb/build;CCDASH_WEB_DIRoverrides both), withindex.htmlfor every route. - The API’s TypeScript types (
web/src/lib/api/types.ts) are generated from the Rust models:cargo test apifails while the file is stale,CCDASH_UPDATE_TYPES=1 cargo test apirewrites it. - After a change to
web/package-lock.json, put the hash thatprefetch-npm-deps web/package-lock.jsonprints intoflake-parts/pkgs/ccdash-web.nix. - The service worker only registers in the built app, so push and the
offline shell are checked against
web/buildserved 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:
| For | Use |
|---|---|
| file modes (0700, 0600) | fsx::set_mode, fsx::ModeExt |
| the collector’s sockets | ipc |
| starting a program | util::program, util::output_within |
| the home directory, ccdash’s own | paths |
| comparing directories and cwds | workspace::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,
deskandlaptop, in two workspaces,acmeandpersonal, 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.
| File | Page | Viewport |
|---|---|---|
now.png | / (after “Recent progress” shows) | 1280×800 |
now-dark.png | /, dark | 1280×800 |
session.png | /sessions/5f1c2a90-… (the checkout session), its 2nd group open | 1280×1000 |
projects.png | /projects | 1280×800 |
history.png | /history?range=1h | 1280×800 |
analytics.png | /analytics/overview?range=7d | 1280×800 |
machines.png | /machines | 1280×500 |
report.png | /reports/acme/dependency-audit--2026-11 | 1280×800 |
phone.png | / | 390×844 |