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

A Windows workstation

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

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

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

1. Install

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

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

It builds ccdash and installs:

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

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

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

2. Optional features

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

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

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

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

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

3. Start at logon

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

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

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

4. The hub’s side

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

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

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

5. Updating

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

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

6. Where things are

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

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

7. Differences

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

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