claude-code-kanban 4.27.0 → 4.28.0-rc.1

package/README.md

@@ -4,92 +4,116 @@
 [![license](https://img.shields.io/npm/l/claude-code-kanban)](LICENSE)
 [![npm downloads](https://img.shields.io/npm/dm/claude-code-kanban)](https://www.npmjs.com/package/claude-code-kanban)
 
-**[Live Demo & Docs](https://nikiforovall.blog/claude-code-kanban/)**
+Start, watch and answer Claude Code sessions from one live board, with a terminal built in.
 
-> Watch Claude Code work, in real time.
+**[Documentation](https://nikiforovall.blog/claude-code-kanban/)**
 
-![Kanban board with session log](assets/shot-session-log.png)
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="website/public/shots/themes/ember-board-dark.webp">
+  <img alt="The board: session sidebar on the left, Pending and In Progress task columns, the agents log below, and the session log on the right" src="website/public/shots/themes/ember-board-light.webp">
+</picture>
 
-## Getting Started
+## Getting started
 
-### 1. Install hooks (one-time setup)
+You need Node.js 20 or later, the `claude` CLI, and `jq` for the hook scripts.
 
-Hooks enable subagent tracking, waiting-for-user detection, and session activity indicators. **Without hooks, you only see tasks — no agent log, no live indicators.**
+### 1. Install the integration (one time)
 
 ```bash
 npx claude-code-kanban --install
 ```
 
-Non-destructive — existing settings in `~/.claude/settings.json` are preserved. Uninstall anytime with `npx claude-code-kanban --uninstall`.
+The installer adds a Claude Code plugin with hooks and skills, and a statusLine script for context use and cost. It asks before each change and keeps your other settings. Without the hooks, the board shows tasks only: no agent log, no live activity, no waiting prompts.
 
-Using another Claude config dir? Pass `--dir=<path>` (or set `CLAUDE_CONFIG_DIR`) to both `--install` and `--uninstall`. The plugin, hooks and statusLine land in that dir, and the hooks write their data under it when Claude Code runs with the same `CLAUDE_CONFIG_DIR`.
+To remove it, run `npx claude-code-kanban --uninstall`. For another Claude config dir, pass the same `--dir=<path>` (or set `CLAUDE_CONFIG_DIR`) to `--install`, `--uninstall` and the server. See [Getting started](https://nikiforovall.blog/claude-code-kanban/getting-started/) for each install step.
 
-### 2. Start the dashboard
+### 2. Start the board
 
 ```bash
 npx claude-code-kanban --open
 ```
 
+The board runs at `http://localhost:3541`. To install the command globally, run `npm install -g claude-code-kanban`, then `claude-code-kanban --open`.
+
 ### 3. Use Claude Code as usual
 
-Tasks, agents, and messages appear on the board automatically — Claude Code writes task files and conversation logs to `~/.claude`, the dashboard watches them and streams updates to the browser via SSE. Moving a card is the one thing that flows the other way: the board notifies the owning session with the card subject and description, so the agent can act on it.
+Run `claude` in any project. You do not configure anything per project. Claude Code writes task files and transcripts to the config dir, and the board watches them and sends each change to the browser.
 
-> **Empty board?** Claude Code ships the task tools off by default on some models — currently Opus 5, Fable 5 — so nothing writes task files and the board stays empty. Turn them on in `~/.claude/settings.json`:
+> **Empty board?** Claude Code ships the task tools off by default on some models, so Claude writes no tasks. Turn them on in the `env` block of Claude Code `settings.json`, then restart Claude Code:
 >
 > ```json
 > { "env": { "CLAUDE_CODE_ENABLE_TODO_TOOLS": "true" } }
 > ```
 >
-> Then restart Claude Code. You can also add a task by hand from the board's Pending column.
+> You can also add a task by hand with **Add task** in the Pending column.
 
 ## Features
 
-- **Real-time Kanban board** — Tasks move through Pending → In Progress → Completed as Claude works
-- **Session log** — The full conversation timeline: prompts, replies, tool calls and results (`Shift+L`)
-- **Agent log** — Live subagent tracking with prompts, duration, status, and idle detection
-- **Task detail panel** — Full description, notes, blockedBy/blocks dependencies, inline editing
-- **Follow & pin** — Follow the latest message live (`Shift+M`), pin the messages that matter
-- **Tool stats & impact** — Per-session tool usage breakdown and file impact
-- **Waiting-for-user indicators** — Amber highlight on sessions needing permission or input
-- **UI approvals** — Allow/deny permission asks and answer questions from the board; on by default, opt out per config dir — [docs](docs/ui-approvals.md)
-- **Agent teams** — Color-coded team members, owner filtering, member count badges
-- **17 color themes** — Dracula, Nord, Catppuccin, Gruvbox, Tokyo Night, and more — each in light and dark
-- **Storage manager** — Inspect disk usage and clean up stale sessions and tasks
-- **Session picker** — Jump to any session in the sidebar with `Shift+P`, filtering by name, project or branch
-- **Keyboard-first** — Press `?` for the full shortcut reference
+### Watch
 
-![Session info](assets/shot-session-info.png)
+- **Live board.** Tasks move through Pending, In Progress and Completed as Claude works. The task panel shows what a task waits on and what it blocks, and you can edit the title and description in place. [Sessions and the board](https://nikiforovall.blog/claude-code-kanban/guides/sessions-and-board/)
+- **Session log.** Every prompt, reply and tool call in order (<kbd>Shift</kbd>+<kbd>L</kbd>). Follow the newest message with <kbd>Shift</kbd>+<kbd>M</kbd>, and pin the messages that matter. [Session log and details](https://nikiforovall.blog/claude-code-kanban/guides/session-details/)
+- **Subagents.** The agents log lists each subagent with its model, status and run time. Open one to read its prompt and response. Team sessions get colored owner badges and an owner filter. [Subagents](https://nikiforovall.blog/claude-code-kanban/guides/subagents/)
+- **Session info and tool stats.** Model, branch, context window use, cost, and which tools ran. The sidebar footer shows your 5-hour and 7-day rate limit use.
+- **Zen mode.** <kbd>Shift</kbd>+<kbd>Z</kbd> shows only the current session in the sidebar, with its context use, scratchpad folder and linked documents.
 
-![Subagent preview](assets/shot-subagent-preview.png)
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="website/public/shots/themes/ember-02-subagent-preview-dark.webp">
+  <img alt="The Agent modal open on the prompt of an Explore subagent, with id, status, tokens, tools and model chips, above the agents log" src="website/public/shots/themes/ember-02-subagent-preview-light.webp">
+</picture>
 
-![Theme picker](assets/shot-theme-picker.png)
+### Drive
 
+- **Answer prompts from the board.** When Claude asks for permission, asks a question or waits for plan approval, the session gets an amber highlight and the ask shows with Allow and Deny buttons or an answer form. The terminal prompt stays open, and the first answer wins. [Answer prompts from the board](https://nikiforovall.blog/claude-code-kanban/guides/waiting-prompts/)
+- **Embedded terminal.** Run a real Claude Code process for any session next to its board (<kbd>Ctrl</kbd>+<kbd>&#96;</kbd>). <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>R</kbd> resumes a past session and <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>S</kbd> swaps to the previous one. The terminal is off by default when the board runs alone. Start it with `--enable-terminal` and open the `#t=<token>` link the server prints. [Embedded terminal](https://nikiforovall.blog/claude-code-kanban/guides/embedded-terminal/)
+- **New session.** <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>N</kbd> opens a dialog to pick a folder, a name, a model, an optional git worktree and a first prompt. Needs the terminal.
+- **Dispatch.** Hand a written task to a new session with `claude-code-kanban dispatch start`, or ask Claude to do it with the `kanban-dispatch` skill. Add `--report` to get the outcome back. Needs the terminal. [Dispatch tasks to other sessions](https://nikiforovall.blog/claude-code-kanban/guides/dispatch/)
+- **Steer with card moves.** Run `/claude-code-kanban:kanban-follow` in a session, then drag its cards. Claude starts, parks or stops the task. [Claude Code plugin skills](https://nikiforovall.blog/claude-code-kanban/guides/plugin-skills/)
 
-## Context Window Monitoring
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="website/public/shots/themes/ember-11-waiting-prompt-dark.webp">
+  <img alt="An Awaiting permission: Bash dialog with the command and Allow and Deny buttons, over a session log that ends with the same waiting ask" src="website/public/shots/themes/ember-11-waiting-prompt-light.webp">
+</picture>
 
-Per-session context usage bars, token/cost breakdowns, and model info in the sidebar and detail panel. The installer copies `context-status.sh` — wire it into your statusline in `~/.claude/settings.json`:
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="website/public/shots/themes/ember-terminal-dark.webp">
+  <img alt="Zen mode with the embedded terminal: one session card and its context use and cost in the sidebar, and Claude Code running in the terminal" src="website/public/shots/themes/ember-terminal-light.webp">
+</picture>
 
-```json
-{
-  "statusLine": {
-    "type": "command",
-    "command": "~/.claude/hooks/context-status.sh | npx -y ccstatusline@latest",
-    "padding": 0
-  }
-}
-```
+### Organize
+
+- **Session groups.** Drag sessions and projects from different folders into one named group in the sidebar. [Session groups](https://nikiforovall.blog/claude-code-kanban/guides/session-groups/)
+- **Filters, search and pins.** Filter by project and activity, search across sessions and tasks, pin a session or make it sticky. <kbd>Shift</kbd>+<kbd>P</kbd> opens the session picker.
+- **Scratchpad and linked documents.** Keep a note per session, project or group (<kbd>N</kbd>), and link files to a session to preview them in one click.
+- **Themes.** 17 color themes, each in light and dark. <kbd>T</kbd> switches the mode.
+- **Keyboard first.** Arrow keys or <kbd>H</kbd> <kbd>J</kbd> <kbd>K</kbd> <kbd>L</kbd> move through tasks, and <kbd>Tab</kbd> moves between the sidebar and the board. Press <kbd>?</kbd> for the full list. [Keyboard shortcuts](https://nikiforovall.blog/claude-code-kanban/reference/keyboard-shortcuts/)
+
+## CLI
 
-The script pipes through, so your existing statusline keeps working.
+With no subcommand, `claude-code-kanban` starts the server. Subcommands talk to a server that already runs:
+
+- `session list|open|view|pin|pins|peek` to read and focus sessions.
+- `preview-doc` and `link-doc` to show or link a file on the board.
+- `dispatch start|done|wait|list` to start sessions with a task and collect their reports.
+
+Run `claude-code-kanban --help` or see the [CLI reference](https://nikiforovall.blog/claude-code-kanban/reference/cli/).
 
 ## Configuration
 
 ```bash
-PORT=8080 npx claude-code-kanban             # Custom port (falls back if busy)
-npx claude-code-kanban --open                # Auto-open browser
-npx claude-code-kanban --dir=~/.claude-work  # Custom Claude config dir (or CLAUDE_CONFIG_DIR)
+PORT=8080 npx claude-code-kanban               # Custom port. If it is busy, the server uses a random free port.
+npx claude-code-kanban --dir=~/.claude-work    # Another Claude config dir (or CLAUDE_CONFIG_DIR)
+npx claude-code-kanban --enable-terminal       # Turn on the embedded terminal
+EDITOR="code -w" npx claude-code-kanban        # Command for Open in editor (default: code)
 ```
 
-Global install: `npm install -g claude-code-kanban`, then `claude-code-kanban --open`.
+- The server listens on `127.0.0.1` only and has no authentication. To reach it from another machine, use `--host` and `--allowed-hosts`, and do it only on a network you trust.
+- UI approvals are on by default. Turn them off or tune them in `<config-dir>/.cck/config.json`.
+- Terminal settings, such as the shell, font size and scrollback, go in the `CCK_TERMINAL` JSON variable.
+
+See [Configuration](https://nikiforovall.blog/claude-code-kanban/reference/configuration/) for every setting, and [Troubleshooting](https://nikiforovall.blog/claude-code-kanban/troubleshooting/) for common problems.
+
+Claude Code Kanban also runs as a tab in [Claude Code Hub](https://nikiforovall.blog/claude-code-kanban/guides/claude-code-hub/), where the terminal is on by default.
 
 ## License
 

package/cli.js

@@ -1,4 +1,7 @@
+const fs = require('fs');
 const path = require('path');
+const { getClaudeDir, displayPath } = require('./lib/claude-dir');
+const { isGroupName, suggestGroupName } = require('./lib/dispatch-groups');
 
 // Help is auto-generated from this table — keep flags/usage in sync with `run` behavior.
 const COMMANDS = {
@@ -83,6 +86,70 @@ const COMMANDS = {
       },
     },
   },
+  dispatch: {
+    summary: 'Start a Claude Code session for a task in cck and collect its report',
+    verbs: {
+      start: {
+        summary: 'Start a session with a task; prints the dispatch id',
+        usage: 'claude-code-kanban dispatch start --cwd <dir> (--spec <text> | --spec-file <path>) [--name <n>] [--group <g>] [--report] [--peer <name>] [--model <m>] [--worktree [name]] [--json]',
+        flags: {
+          '--cwd <dir>': 'Folder to run in (a known project, default: current dir)',
+          '--spec <text>': 'The task, self-contained',
+          '--spec-file <path>': 'Read the task from a file',
+          '--name <n>': 'Session name',
+          '--group <g>': 'Show it with this session in a kebab-case group (default: this session\'s group)',
+          '--report': 'Ask it to report its outcome back to this session',
+          '--peer <name>': 'This session\'s peer name; it sends questions and findings there with SendMessage',
+          '--model <m>': 'fable, opus, sonnet or haiku',
+          '--worktree [name]': 'Run in a new git worktree',
+          '--json': 'Output JSON',
+        },
+        run: runDispatchStartCli,
+      },
+      done: {
+        summary: 'Report the outcome of a dispatch (run by the started session)',
+        usage: 'claude-code-kanban dispatch done <id> --cap <cap> --outcome succeeded|failed (--summary <text> | --summary-file <path>)',
+        flags: {
+          '<id>': 'Dispatch id from the preamble',
+          '--cap <cap>': 'Capability from the preamble',
+          '--outcome <o>': 'succeeded or failed',
+          '--summary <text>': 'What changed, what was found, what remains',
+          '--summary-file <path>': 'Read the summary from a file',
+        },
+        run: runDispatchDoneCli,
+      },
+      wait: {
+        summary: 'Wait until a dispatch settles; a timeout is a checkpoint, not a failure',
+        usage: 'claude-code-kanban dispatch wait [<id>...] [--timeout <dur>] [--json]',
+        flags: {
+          '<id>': 'Dispatches to wait on (default: all started by this session)',
+          '--timeout <dur>': 'How long to wait, e.g. 90s, 15m, 1h (default: 10m)',
+          '--json': 'Output JSON',
+        },
+        run: runDispatchWaitCli,
+      },
+      list: {
+        summary: 'List dispatches started by this session',
+        usage: 'claude-code-kanban dispatch list [--all] [--json]',
+        flags: {
+          '--all': 'Every dispatch on this board',
+          '--json': 'Output JSON',
+        },
+        run: runDispatchListCli,
+      },
+    },
+  },
+  skills: {
+    summary: 'Print a skill guide bundled with this version',
+    verbs: {
+      get: {
+        summary: 'Print the guide for a skill',
+        usage: 'claude-code-kanban skills get <name>',
+        flags: { '<name>': 'Skill name, e.g. dispatch' },
+        run: runSkillsGetCli,
+      },
+    },
+  },
 };
 
 function runCli(argv) {
@@ -197,8 +264,25 @@ function getArgValue(args, name) {
   return args[idx + 1] && !args[idx + 1].startsWith('--') ? args[idx + 1] : null;
 }
 
-function cliPort() { return process.env.PORT || 3541; }
-function unreachable() { return `Cannot reach cck server on port ${cliPort()}. Start it first with "claude-code-kanban".`; }
+// The hub runs one cck per config dir, each on its own port, so 3541 can be another dir's board.
+// The server's beacon in this config dir names the right one; PORT still wins when set.
+function cliPort() {
+  if (process.env.PORT) return process.env.PORT;
+  const { port, pid } = readCckJson('server.json') || {};
+  return port && pid && isPidAlive(pid) ? port : 3541;
+}
+
+function readCckJson(name) {
+  try { return JSON.parse(fs.readFileSync(path.join(getClaudeDir(), '.cck', name), 'utf8')); } catch (_) { return null; }
+}
+
+// EPERM means the process exists but belongs to someone else.
+function isPidAlive(pid) {
+  try { process.kill(pid, 0); return true; } catch (e) { return e.code === 'EPERM'; }
+}
+function unreachable() {
+  return `Cannot reach cck server for ${displayPath(getClaudeDir())} on port ${cliPort()}. Start it first with "claude-code-kanban".`;
+}
 
 class CliUnreachable extends Error { constructor() { super(unreachable()); this.code = 'unreachable'; } }
 
@@ -213,15 +297,19 @@ async function cliFetch(urlPath, init) {
 
 // Every write verb posts JSON and reports failure the same way; `label` names the verb
 // in the error line. Returns false when the server refused, so callers just return 1.
-async function cliPostJson(urlPath, body, label) {
+// Returns the parsed response body ({} when empty), or null after printing the failure.
+async function cliPostJson(urlPath, body, label, headers = {}) {
   const res = await cliFetch(urlPath, {
     method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
+    headers: { 'Content-Type': 'application/json', ...headers },
     body: JSON.stringify(body)
   });
-  if (res.ok) return true;
-  console.error(`${label} failed (${res.status}): ${await res.text()}`);
-  return false;
+  const text = await res.text();
+  let parsed = {};
+  try { parsed = text ? JSON.parse(text) : {}; } catch (_) { /* not JSON */ }
+  if (res.ok) return parsed;
+  console.error(`${label} failed (${res.status}): ${parsed.error || text}`);
+  return null;
 }
 
 function reportCliError(e) {
@@ -592,4 +680,144 @@ async function runSessionPeekCli(args) {
   } catch (e) { reportCliError(e); return 1; }
 }
 
+function positionals(args, valueFlags) {
+  return args.filter((a, i) => !a.startsWith('--') && !valueFlags.includes(args[i - 1]));
+}
+
+// The server matches the folder against known project paths by string, so an 8.3 short name
+// or a differently cased drive letter from the shell must become the long, canonical form.
+function canonicalDir(dir) {
+  try { return fs.realpathSync.native(path.resolve(dir)); } catch (_) { return path.resolve(dir); }
+}
+
+function textArg(args, name) {
+  const file = getArgValue(args, `${name}-file`);
+  return file ? fs.readFileSync(path.resolve(file), 'utf8') : getArgValue(args, name);
+}
+
+function parseDuration(raw, fallbackSec) {
+  if (!raw) return fallbackSec;
+  const m = /^(\d+(?:\.\d+)?)(s|m|h)?$/.exec(raw);
+  if (!m) return null;
+  return Number(m[1]) * ({ s: 1, m: 60, h: 3600 }[m[2] || 's']);
+}
+
+function printDispatch(r) {
+  const head = `${r.id}  ${r.status.padEnd(9)} session=${r.session}${r.name ? `  ${r.name}` : ''}`;
+  console.log(r.summary ? `${head}\n  ${r.summary}` : head);
+}
+
+async function runDispatchStartCli(args) {
+  const token = readCckJson('terminal-token.json')?.token;
+  if (!token) {
+    console.error(`No terminal token for ${displayPath(getClaudeDir())}. The cck server must be running with the terminal enabled.`);
+    return 1;
+  }
+  let spec;
+  try { spec = textArg(args, 'spec'); } catch (e) { console.error(e.message); return 1; }
+  if (!spec) {
+    printLeafHelp('dispatch start', COMMANDS.dispatch.verbs.start);
+    return 1;
+  }
+  const hasGroup = args.some(a => a === '--group' || a.startsWith('--group='));
+  const group = hasGroup ? getArgValue(args, 'group') || '' : null;
+  if (hasGroup && !isGroupName(group)) {
+    const hint = suggestGroupName(group);
+    console.error(`Group names are kebab-case${hint ? `: try --group ${hint}` : ', e.g. auth-refactor'}`);
+    return 1;
+  }
+  const worktree = args.includes('--worktree') ? getArgValue(args, 'worktree') || true : false;
+  const body = {
+    cwd: canonicalDir(getArgValue(args, 'cwd') || '.'),
+    spec,
+    name: getArgValue(args, 'name'),
+    model: getArgValue(args, 'model'),
+    worktree,
+    group,
+    report: args.includes('--report'),
+    peer: getArgValue(args, 'peer') || null,
+    parent: process.env.CLAUDE_CODE_SESSION_ID || null,
+  };
+  try {
+    const out = await cliPostJson('/api/dispatch', body, 'Dispatch', { 'x-terminal-token': token });
+    if (!out) return 1;
+    if (args.includes('--json')) console.log(JSON.stringify(out, null, 2));
+    else console.log(`Started ${out.dispatch} (session ${out.session}) in ${out.cwd}${out.group ? ` [${out.group}]` : ''}`);
+    return 0;
+  } catch (e) { reportCliError(e); return 1; }
+}
+
+async function runDispatchDoneCli(args) {
+  const [id] = positionals(args, ['--cap', '--outcome', '--summary', '--summary-file']);
+  let summary;
+  try { summary = textArg(args, 'summary'); } catch (e) { console.error(e.message); return 1; }
+  const body = { cap: getArgValue(args, 'cap'), outcome: getArgValue(args, 'outcome'), summary };
+  if (!id || !body.cap || !body.outcome) {
+    printLeafHelp('dispatch done', COMMANDS.dispatch.verbs.done);
+    return 1;
+  }
+  try {
+    if (!await cliPostJson(`/api/dispatch/${encodeURIComponent(id)}/done`, body, 'Report')) return 1;
+    console.log(`Reported ${id}: ${body.outcome}`);
+    return 0;
+  } catch (e) { reportCliError(e); return 1; }
+}
+
+function dispatchQuery(ids, all = false) {
+  const q = new URLSearchParams();
+  if (ids.length) q.set('ids', ids.join(','));
+  else if (!all && process.env.CLAUDE_CODE_SESSION_ID) q.set('parent', process.env.CLAUDE_CODE_SESSION_ID);
+  return q;
+}
+
+async function runDispatchWaitCli(args) {
+  const timeoutRaw = getArgValue(args, 'timeout');
+  const timeoutSec = parseDuration(timeoutRaw, 600);
+  if (timeoutSec === null) {
+    console.error(`Invalid --timeout value: ${timeoutRaw}`);
+    return 1;
+  }
+  const q = dispatchQuery(positionals(args, ['--timeout']));
+  const deadline = Date.now() + timeoutSec * 1000;
+  try {
+    let out;
+    do {
+      q.set('wait', String(Math.max(1, Math.min(120, Math.ceil((deadline - Date.now()) / 1000)))));
+      const res = await cliFetch(`/api/dispatch?${q}`);
+      out = await res.json();
+    } while (out.timeout && Date.now() < deadline);
+    if (args.includes('--json')) console.log(JSON.stringify(out, null, 2));
+    else {
+      for (const r of out.settled) printDispatch(r);
+      if (out.running.length) console.log(`${out.timeout ? 'Timed out; still running' : 'Still running'}: ${out.running.map(r => r.id).join(' ')}`);
+      if (!out.settled.length && !out.running.length) console.log('No dispatches to wait on.');
+    }
+    return 0;
+  } catch (e) { reportCliError(e); return 1; }
+}
+
+async function runDispatchListCli(args) {
+  try {
+    const res = await cliFetch(`/api/dispatch?${dispatchQuery([], args.includes('--all'))}`);
+    const { settled, running } = await res.json();
+    const rows = [...running, ...settled].sort((a, b) => b.startedAt - a.startedAt);
+    if (args.includes('--json')) console.log(JSON.stringify(rows, null, 2));
+    else if (!rows.length) console.log('No dispatches.');
+    else rows.forEach(printDispatch);
+    return 0;
+  } catch (e) { reportCliError(e); return 1; }
+}
+
+async function runSkillsGetCli(args) {
+  const name = args.find(a => !a.startsWith('--'));
+  const file = name && /^[a-z][a-z-]*$/.test(name) ? path.join(__dirname, 'skill-guides', `${name}.md`) : null;
+  if (!file || !fs.existsSync(file)) {
+    const known = fs.readdirSync(path.join(__dirname, 'skill-guides')).map(f => f.replace(/\.md$/, ''));
+    console.error(`Unknown skill guide: ${name || '(none)'}. Known: ${known.join(', ')}`);
+    return 1;
+  }
+  process.stdout.write(fs.readFileSync(file, 'utf8'));
+  return 0;
+}
+
 module.exports = { runCli };

package/lib/claude-dir.js

@@ -50,4 +50,4 @@ function displayPath(p) {
   return rel.split(path.sep).join('/');
 }
 
-module.exports = { getArgValue, getClaudeDir, claudeCliEnv, displayPath, storageNamespace };
+module.exports = { getArgValue, getClaudeDir, claudeCliEnv, isDefaultClaudeDir, displayPath, storageNamespace };

package/lib/dispatch-groups.js

@@ -0,0 +1,93 @@
+// Transient session groups: `dispatch start --group` (or the starter's own group) puts
+// the started session and its starter together. A group lives while any member's claude
+// runs, and for a grace period after; once none runs, only pinned members stay in it.
+// The map is on disk so a pinned group outlives a server restart.
+
+const GROUP_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const MAX_GROUP = 64;
+// Covers a claude that has started but not yet registered, a resume, and registry lag.
+const GRACE_MS = 60 * 1000;
+
+function isGroupName(s) {
+  return typeof s === 'string' && s.length <= MAX_GROUP && GROUP_RE.test(s);
+}
+
+function suggestGroupName(s) {
+  return String(s ?? '')
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, MAX_GROUP)
+    .replace(/-+$/, '');
+}
+
+/**
+ * @param {object} o
+ * @param {() => object|null} o.load returns `{sessions: {[id]: group}}` or null
+ * @param {(data: object) => void} o.save
+ * @param {(id: string) => boolean} o.isAlive
+ * @param {() => Set<string>} o.pinnedIds
+ */
+function createGroupStore({ load, save, isAlive, pinnedIds, now = Date.now }) {
+  const members = new Map();
+  const liveAt = new Map();
+  const saved = load()?.sessions;
+  if (saved && typeof saved === 'object') {
+    for (const [id, g] of Object.entries(saved)) if (isGroupName(g)) members.set(id, g);
+  }
+  for (const g of members.values()) liveAt.set(g, now());
+
+  const persist = () => save({ version: 1, sessions: Object.fromEntries(members) });
+
+  function join(group, ids) {
+    let changed = false;
+    for (const id of ids) {
+      if (!id || members.get(id) === group) continue;
+      members.set(id, group);
+      changed = true;
+    }
+    liveAt.set(group, now());
+    if (changed) persist();
+  }
+
+  function refresh() {
+    const t = now();
+    const byGroup = new Map();
+    for (const [id, g] of members) {
+      if (!byGroup.has(g)) byGroup.set(g, []);
+      byGroup.get(g).push(id);
+    }
+    let pinned = null;
+    let changed = false;
+    for (const [g, ids] of byGroup) {
+      if (ids.some(isAlive)) {
+        liveAt.set(g, t);
+        continue;
+      }
+      if (t - (liveAt.get(g) ?? 0) <= GRACE_MS) continue;
+      pinned ??= pinnedIds();
+      for (const id of ids) {
+        if (pinned.has(id)) continue;
+        members.delete(id);
+        changed = true;
+      }
+      if (!ids.some((id) => pinned.has(id))) liveAt.delete(g);
+    }
+    if (changed) persist();
+  }
+
+  function groupOf(id) {
+    refresh();
+    return members.get(id) || null;
+  }
+
+  function snapshot() {
+    refresh();
+    return members;
+  }
+
+  return { join, groupOf, snapshot };
+}
+
+module.exports = { createGroupStore, isGroupName, suggestGroupName, GRACE_MS };