Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Configuration

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

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

1. NixOS module (hub)

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

2. Home Manager module (collector)

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

3. Hub keys

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

4. Collector keys

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

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