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

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: