claude-code-kanban 7.20.0 → 7.22.0

package/cli.js

@@ -3,6 +3,9 @@ const path = require('node:path');
 const { getClaudeDir, displayPath } = require('./lib/claude-dir');
 const { linkUrl } = require('./public/link-url');
 const { sessionProjectKey } = require('./public/project-match');
+const { MODELS } = require('./lib/terminal');
+
+const MODEL_HELP = [...MODELS].join(', ').replace(/, (\w+)$/, ' or $1');
 // Help is auto-generated from this table — keep flags/usage in sync with `run` behavior.
 const SESSION_FLAG = '--session <id>';
 const SESSION_FLAG_HELP = 'Session, full id or unique prefix (default: $PREVIEW_SESSION, else $CLAUDE_CODE_SESSION_ID)';
@@ -98,6 +101,68 @@ const COMMANDS = {
       },
     },
   },
+  addon: {
+    summary: 'Put web pages on the dock rail beside the embedded terminal, for this session or every session',
+    verbs: {
+      add: {
+        summary: 'Add a URL to the dock rail; the user opens it from the rail',
+        usage: 'claude-code-kanban addon add <url> | --manifest <dir> [--title <text>] [--icon <glyph>] [--param <k=v> ...] [--global [--run <cmd> [--cwd <dir>]] [--offline]] [--session <id>] [--json]',
+        flags: {
+          '<url>': 'An http(s) URL. {sessionId}, {cwd} and {project} are filled for each session, {<name>} from --param',
+          '--manifest <dir>': 'Add the add-on in <dir> from its addon.json (url, title, icon, run), as a global entry that runs in <dir>. Its id names the entry, so a repeat add updates it',
+          '--offline': 'With --global: write the board\'s addons.json directly, with no board running and no terminal token. A running board picks the change up',
+          '--title <text>': 'Rail and header title (default: the host)',
+          '--icon <glyph>': 'One or two characters on the rail button (default: the first letter of the title)',
+          '--param <k=v>': 'A value for {k} in the URL; repeat for each. `addon set` changes it for one session',
+          '--global': 'Show it on the rail of every session. Use only when the user asks for every session',
+          '--run <cmd>': 'With --global: the command that starts the page\'s server. The board runs it when the rail opens the page and its localhost port does not answer, with PORT set',
+          '--cwd <dir>': 'Absolute folder to run --run in (default: the board\'s folder)',
+          [SESSION_FLAG]: SESSION_FLAG_HELP,
+          '--json': 'Output JSON (the add-on entry)',
+        },
+        notes: 'Quote the URL so the shell keeps the braces. Each value is URL-encoded when filled. A placeholder with no value is refused. A session add-on goes when the session expires; a global one stays until `addon rm`. The same URL added again prints the entry it already has; with --run it takes the new command. --run needs the board\'s terminal, like `dispatch start`, unless --offline. The server stops with the board; its output goes to .cck/addons/<id>.log.',
+        examples: [
+          'claude-code-kanban addon add --manifest ~/.claude-hub/extensions/git-changes/examples/git-changes --offline',
+          'claude-code-kanban addon add "http://localhost:4100/?cwd={cwd}" --title Changes',
+          'claude-code-kanban addon add "http://localhost:4200/{sessionId}" --title Notes --global',
+          'claude-code-kanban addon add "http://localhost:4117/?cwd={cwd}" --title Changes --global --run "node server.js" --cwd C:/tools/changes',
+        ],
+        run: runAddonAddCli,
+      },
+      list: {
+        summary: 'List the add-ons on a session\'s rail: the global ones, then the session\'s',
+        usage: 'claude-code-kanban addon list [--session <id>] [--json]',
+        flags: {
+          [SESSION_FLAG]: SESSION_FLAG_HELP,
+          '--json': 'Output JSON ({global, session, params: {<id>: {k: v}}})',
+        },
+        run: runAddonListCli,
+      },
+      set: {
+        summary: 'Set a param of an add-on for one session; an empty value goes back to the add-on\'s own',
+        usage: 'claude-code-kanban addon set <id> <k=v> ... [--session <id>]',
+        flags: {
+          '<id>': 'The id `addon add` or `addon list` printed',
+          '<k=v>': 'The new value of {k}; k= with no value drops this session\'s value',
+          [SESSION_FLAG]: SESSION_FLAG_HELP,
+        },
+        examples: ['claude-code-kanban addon set a3 repo=claude-code-hub'],
+        run: runAddonSetCli,
+      },
+      rm: {
+        summary: 'Take an add-on off the rail: a global one from every session',
+        usage: 'claude-code-kanban addon rm <id> | --key <key> [--offline] [--session <id>]',
+        flags: {
+          '<id>': 'The id `addon add` or `addon list` printed',
+          '--key <key>': 'The global add-on with this key, the id in its addon.json. No such add-on is not an error',
+          '--offline': 'Remove a global add-on from the board\'s addons.json directly, with no board running',
+          [SESSION_FLAG]: SESSION_FLAG_HELP,
+        },
+        examples: ['claude-code-kanban addon rm a3', 'claude-code-kanban addon rm --key git-changes --offline'],
+        run: runAddonRmCli,
+      },
+    },
+  },
   session: {
     summary: 'List, search, open, inspect and group Claude Code sessions',
     verbs: {
@@ -333,23 +398,24 @@ const COMMANDS = {
     verbs: {
       start: {
         summary: 'Start claude in cck\'s terminal with a task; prints the session id',
-        usage: 'claude-code-kanban dispatch start --cwd <dir> (--spec <text> | --spec-file <path>) [--name <n>] [--group <g>] [--model <m>] [--worktree [name]] [--task-list [id]] [--json] [-- <claude args>...]',
+        usage: 'claude-code-kanban dispatch start --cwd <dir> (--spec <text> | --spec-file <path>) (--child | --group <g>) [--name <n>] [--model <m>] [--worktree [name]] [--task-list [id]] [--json] [-- <claude args>...]',
         flags: {
           '--cwd <dir>': 'Folder to run in (any existing folder, default: current dir)',
           '--spec <text>': 'The task, self-contained; sent as the first message',
           '--spec-file <path>': 'Read the task from a file',
           '--name <n>': 'Session name; also its peer name for SendMessage',
-          '--group <g>': 'Add it to this group: a name, path or id. The groups it makes are transient (see `help group list`)',
-          '--model <m>': 'fable, opus, sonnet or haiku',
+          '--child': 'Part of your work: its card shows under yours, wherever yours is. Needs a Claude Code session',
+          '--group <g>': 'Separate work: add it to this group, a name, path or id. The groups it makes are transient (see `help group list`)',
+          '--model <m>': MODEL_HELP,
           '--worktree [name]': 'Run in a new git worktree',
           '--task-list [id]': 'Use this task list instead of its own (default: this session\'s list), so its cards show on one board with yours. Off unless given',
           '--json': 'Output JSON',
           '-- <claude args>': 'Passed to claude as they are, e.g. --permission-mode auto. No quotes, % or control characters; cck sets --session-id, --name, --model and --worktree',
         },
-        notes: 'Needs the terminal token, so it runs on the machine of the cck server. cck sends no report: say in the spec how the session reports back. Run `claude-code-kanban skills get dispatch` for how to write the spec.',
+        notes: 'Pass one of --child or --group. Needs the terminal token, so it runs on the machine of the cck server. cck sends no report: say in the spec how the session reports back. Run `claude-code-kanban skills get dispatch` for how to write the spec.',
         examples: [
-          'claude-code-kanban dispatch start --cwd . --spec-file spec.md --name fix-login-redirect --group auth-refactor --model sonnet -- --permission-mode auto',
-          'claude-code-kanban dispatch start --cwd . --spec-file spec.md --name api-worker --task-list',
+          'claude-code-kanban dispatch start --cwd . --spec-file spec.md --name fix-login-redirect --child --model sonnet -- --permission-mode auto',
+          'claude-code-kanban dispatch start --cwd . --spec-file spec.md --name api-worker --group auth-refactor --task-list',
         ],
         run: runDispatchStartCli,
       },
@@ -376,6 +442,24 @@ const COMMANDS = {
       },
     },
   },
+  new: {
+    summary: 'Start claude in the board\'s terminal from any shell, and show it there',
+    usage: 'claude-code-kanban new [prompt...] [--cwd <dir>] [--name <n>] [--model <m>] [--json] [-- <claude args>...]',
+    flags: {
+      '[prompt...]': 'First message; the words are joined with spaces. None starts an empty session',
+      '--cwd <dir>': 'Folder to run in (default: current dir)',
+      '--name <n>': 'Session name',
+      '--model <m>': MODEL_HELP,
+      '--json': 'Output JSON: {session, cwd}',
+      '-- <claude args>': 'Passed to claude as they are, e.g. --permission-mode auto',
+    },
+    notes: 'For the user at a shell, not for agents: agents use `dispatch start`. A board tab with the terminal on must be open, else the session is ended; the tab shows it, and under the hub the hub switches to Kanban. Needs the terminal token, so it runs on the machine of the cck server.',
+    examples: [
+      'claude-code-kanban new',
+      'claude-code-kanban new fix the login redirect -- --permission-mode auto',
+    ],
+    run: runNewCli,
+  },
   terminal: {
     summary: 'Read the terminals running in cck',
     verbs: {
@@ -408,8 +492,16 @@ for (const [noun, cmd] of Object.entries(COMMANDS)) {
   cmd.name = noun;
   for (const [verb, v] of Object.entries(cmd.verbs || {})) v.name = `${noun} ${verb}`;
 }
+// Words after `--` belong to claude, so cck's own --help and --version are looked for before it.
+function ownArgs(argv) {
+  const sep = argv.indexOf('--');
+  return sep === -1 ? argv : argv.slice(0, sep);
+}
+const hasOwnFlag = (a, ...flags) => ownArgs(a).some((x) => flags.includes(x));
+const hasHelp = (a) => hasOwnFlag(a, '--help', '-h');
+
 function runCli(argv) {
-  if (argv.includes('--version') || argv.includes('-v')) {
+  if (hasOwnFlag(argv, '--version', '-v')) {
     console.log(require('./package.json').version);
     process.exit(0);
   }
@@ -435,10 +527,10 @@ function runCli(argv) {
   }
   if (cli.kind === 'noun') {
     printNounHelp(cli.noun);
-    process.exit(argv.includes('--help') || argv.includes('-h') ? 0 : 1);
+    process.exit(hasHelp(argv) ? 0 : 1);
   }
   if (cli.kind === 'leaf') {
-    if (cli.args.includes('--help') || cli.args.includes('-h')) {
+    if (hasHelp(cli.args)) {
       printLeafHelp(cli.entry);
       process.exit(0);
     }
@@ -452,7 +544,6 @@ function runCli(argv) {
 
 function resolveCliCommand(argv) {
   const noun = argv[2] && !argv[2].startsWith('-') ? argv[2] : null;
-  const hasHelp = (a) => a.includes('--help') || a.includes('-h');
   if (!noun) return hasHelp(argv) ? { kind: 'help' } : { kind: 'server' };
   if (noun === 'help') return { kind: 'help', target: argv[3], verb: argv[4] };
   if (!Object.hasOwn(COMMANDS, noun)) return { kind: 'unknown-noun', noun };
@@ -506,8 +597,8 @@ function printTopHelp() {
 
 function printNounHelp(noun) {
   const entry = COMMANDS[noun];
-  console.log(`${entry.summary}\n`);
   if (entry.verbs) {
+    console.log(`${entry.summary}\n`);
     console.log(`Usage: claude-code-kanban ${noun} <subcommand> [args] [--flags]\n`);
     console.log('Subcommands:');
     for (const [vName, v] of Object.entries(entry.verbs)) {
@@ -678,9 +769,11 @@ async function postDocLink(target, sessionId, { unlink = false, open = false } =
   } catch (e) { reportCliError(e); return 1; }
 }
 
+const sessionArgOf = (args) => getArgValue(args, 'session') || process.env.PREVIEW_SESSION || process.env.CLAUDE_CODE_SESSION_ID;
+
 // Resolved to the full id because the browser keys linked docs by it, so a prefix won't match.
 async function resolveSessionArg(entry, args, why) {
-  const sessionArg = getArgValue(args, 'session') || process.env.PREVIEW_SESSION || process.env.CLAUDE_CODE_SESSION_ID;
+  const sessionArg = sessionArgOf(args);
   if (!sessionArg) {
     usageError(entry, `--session is required: ${why}`);
     return null;
@@ -763,7 +856,181 @@ async function runPaneListCli(args, entry) {
     const layout = await cliGetJson(panesPath(resolved.id), 'Pane list');
     if (args.includes('--json')) console.log(JSON.stringify(layout, null, 2));
     else if (!layout.panes.length) console.log(`No panes for session ${resolved.id.slice(0, 8)}.`);
-    else printTable(['ID', 'KIND', 'TITLE', 'TARGET'], layout.panes.map((p) => [p.id, p.kind, p.title, p.target]));
+    else printTable(['ID', 'KIND', 'TITLE', 'TARGET'], layout.panes.map((p) => [p.id, p.dock ? `${p.kind} (dock)` : p.kind, p.title, p.target]));
+    return 0;
+  } catch (e) { reportCliError(e); return 1; }
+}
+
+const ADDONS_WHY = 'a session add-on is stored with its session.';
+
+// `k=v` words; a repeated `--param` takes one each. Returns null after printing the error.
+function addonParams(entry, words) {
+  const params = {};
+  for (const w of words) {
+    const i = w.indexOf('=');
+    if (i < 1) {
+      usageError(entry, `Expected k=v, got: ${w}`);
+      return null;
+    }
+    params[w.slice(0, i)] = w.slice(i + 1);
+  }
+  return params;
+}
+
+const argValues = (args, name) =>
+  args.flatMap((a, i) => {
+    if (a.startsWith(`--${name}=`)) return [a.slice(name.length + 3)];
+    return a === `--${name}` && args[i + 1] && !args[i + 1].startsWith('--') ? [args[i + 1]] : [];
+  });
+
+// A global add-on needs no session; take one only when one is named or set.
+async function optionalSession(entry, args) {
+  return sessionArgOf(args) ? resolveSessionArg(entry, args, ADDONS_WHY) : { id: null };
+}
+
+const sessionQuery = (resolved) => (resolved.id ? `?session=${encodeURIComponent(resolved.id)}` : '');
+
+// The add-on's own manifest (addon.json); the store checks the fields it keeps.
+function readAddonManifest(entry, dir) {
+  const file = path.join(dir, 'addon.json');
+  let m;
+  try {
+    m = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (e) {
+    usageError(entry, `Cannot read ${file}: ${e.code || e.message}`);
+    return null;
+  }
+  if (m?.kind !== 'addon' || typeof m.id !== 'string' || typeof m.url !== 'string') {
+    usageError(entry, `${file} is not an add-on manifest: it needs "kind": "addon", an id and a url`);
+    return null;
+  }
+  return m;
+}
+
+// With no board: the store writes addons.json itself, and a running board reads the change.
+function offlineAddons() {
+  const { createAddonStore } = require('./lib/addons');
+  const { stampedJsonFile } = require('./lib/stamped-json-file');
+  const { writeJsonAtomic } = require('./lib/write-json-atomic');
+  return createAddonStore(stampedJsonFile(path.join(getClaudeDir(), '.cck', 'addons.json'), writeJsonAtomic));
+}
+
+async function runAddonAddCli(args, entry) {
+  const [urlArg] = positionals(args, ['--session', '--title', '--icon', '--param', '--run', '--cwd', '--manifest']);
+  const manifestDir = getArgValue(args, 'manifest');
+  if (!urlArg && !manifestDir) {
+    printLeafHelp(entry);
+    return 1;
+  }
+  if (urlArg && manifestDir) return usageError(entry, '--manifest takes the URL from addon.json');
+  let spec;
+  if (manifestDir) {
+    if (getArgValue(args, 'run') || getArgValue(args, 'cwd')) return usageError(entry, '--manifest takes run from addon.json and runs it in that folder');
+    const dir = path.resolve(manifestDir);
+    const m = readAddonManifest(entry, dir);
+    if (!m) return 1;
+    spec = { url: m.url, run: m.run, cwd: m.run && dir, title: m.title, icon: m.icon, key: m.id, isGlobal: true };
+  } else {
+    const cwd = getArgValue(args, 'cwd');
+    spec = { url: urlArg, run: getArgValue(args, 'run'), cwd: cwd && path.resolve(cwd), isGlobal: args.includes('--global') };
+  }
+  const { url, run, cwd, key, isGlobal } = spec;
+  const params = addonParams(entry, argValues(args, 'param'));
+  if (!params) return 1;
+  const offline = args.includes('--offline');
+  if (offline && !isGlobal) return usageError(entry, '--offline needs --global');
+  if (run && !isGlobal) return usageError(entry, '--run needs --global');
+  if (cwd && !run) return usageError(entry, '--cwd needs --run');
+  const needsToken = run && !offline;
+  const token = needsToken ? readTerminalToken() : null;
+  if (needsToken && !token) return 1;
+  const resolved = isGlobal ? { id: 'global' } : await resolveSessionArg(entry, args, ADDONS_WHY);
+  if (!resolved) return 1;
+  try {
+    const icon = getArgValue(args, 'icon') || spec.icon;
+    const title = getArgValue(args, 'title') || spec.title || '';
+    const fields = { ...(key && { key }), url, title, ...(icon && { icon }), params, ...(run && { run, ...(cwd && { cwd }) }) };
+    const out = offline
+      ? offlineAddons().add(resolved.id, fields)
+      : await cliPostJson('/api/addons', { scope: resolved.id, ...fields }, 'Add-on add', token ? { 'x-terminal-token': token } : undefined);
+    if (!out) return 1;
+    if (args.includes('--json')) console.log(JSON.stringify(out.addon, null, 2));
+    else console.log(`${out.addon.id}  ${out.addon.title} (${isGlobal ? 'every session' : 'this session'})${out.added ? '' : ' (already there)'}`);
+    return 0;
+  } catch (e) { reportCliError(e); return 1; }
+}
+
+async function runAddonListCli(args, entry) {
+  const resolved = await optionalSession(entry, args);
+  if (!resolved) return 1;
+  try {
+    const list = await cliGetJson(`/api/addons${sessionQuery(resolved)}`, 'Add-on list');
+    if (args.includes('--json')) {
+      console.log(JSON.stringify(list, null, 2));
+      return 0;
+    }
+    const rows = [...list.global.map((a) => ['global', a]), ...list.session.map((a) => ['session', a])].map(([scope, a]) => {
+      const params = Object.entries({ ...a.params, ...list.params[a.id] }).map(([k, v]) => `${k}=${v}`).join(' ');
+      return [a.id, scope, a.title, a.url, params];
+    });
+    if (!rows.length) console.log('No add-ons on the rail.');
+    else printTable(['ID', 'SCOPE', 'TITLE', 'URL', 'PARAMS'], rows);
+    return 0;
+  } catch (e) { reportCliError(e); return 1; }
+}
+
+async function runAddonSetCli(args, entry) {
+  const [id, ...words] = positionals(args, ['--session']);
+  if (!id || !words.length) {
+    printLeafHelp(entry);
+    return 1;
+  }
+  const params = addonParams(entry, words);
+  if (!params) return 1;
+  const resolved = await resolveSessionArg(entry, args, 'a param value is set per session.');
+  if (!resolved) return 1;
+  try {
+    if (!await cliSendJson('PATCH', `/api/addons/${encodeURIComponent(id)}`, { session: resolved.id, params }, 'Add-on set')) return 1;
+    console.log(`Set ${Object.keys(params).join(', ')} of ${id} for session ${resolved.id.slice(0, 8)}`);
+    return 0;
+  } catch (e) { reportCliError(e); return 1; }
+}
+
+async function runAddonRmCli(args, entry) {
+  const [idArg] = positionals(args, ['--session', '--key']);
+  const key = getArgValue(args, 'key');
+  if (!idArg && !key) {
+    printLeafHelp(entry);
+    return 1;
+  }
+  if (idArg && key) return usageError(entry, 'Pass an id or --key, not both');
+  const offline = args.includes('--offline');
+  const resolved = offline ? {} : await optionalSession(entry, args);
+  if (!resolved) return 1;
+  try {
+    const store = offline ? offlineAddons() : null;
+    const global = key && (store ? store.list(null) : await cliGetJson('/api/addons', 'Add-on list')).global;
+    const id = idArg ?? global.find((a) => a.key === key)?.id;
+    if (!id) {
+      console.log(`No add-on has the key ${key}`);
+      return 0;
+    }
+    if (store) {
+      if (!store.remove(null, id)) {
+        console.error(`No global add-on ${id}`);
+        return 1;
+      }
+      console.log(`Removed add-on ${id} from every session`);
+      return 0;
+    }
+    const out = await cliSendJson(
+      'DELETE',
+      `/api/addons/${encodeURIComponent(id)}${sessionQuery(resolved)}`,
+      undefined,
+      'Add-on rm',
+    );
+    if (!out) return 1;
+    console.log(`Removed add-on ${id}${out.scope === 'global' ? ' from every session' : ''}`);
     return 0;
   } catch (e) { reportCliError(e); return 1; }
 }
@@ -1426,10 +1693,28 @@ function readTerminalToken() {
   return token;
 }
 
+function splitClaudeArgs(argv) {
+  const args = ownArgs(argv);
+  return { args, claudeArgs: argv.slice(args.length + 1) };
+}
+
+// A help key is `--name`, `--name <value>` or `--name [value]`; anything else is a positional
+// or the `--` separator. test/cli-flags.test.js checks every key in COMMANDS against this.
+const FLAG_KEY = /^(--[a-z][\w-]*)(?: (<[^>]+>|\[[^\]]+\]))?$/;
+function flagSpec(entry) {
+  const names = [];
+  const valueFlags = [];
+  for (const key of Object.keys(entry.flags || {})) {
+    const m = key.match(FLAG_KEY);
+    if (!m) continue;
+    names.push(m[1]);
+    if (m[2]?.startsWith('<')) valueFlags.push(m[1]);
+  }
+  return { names, valueFlags };
+}
+
 async function runDispatchStartCli(argv) {
-  const sep = argv.indexOf('--');
-  const args = sep === -1 ? argv : argv.slice(0, sep);
-  const claudeArgs = sep === -1 ? [] : argv.slice(sep + 1);
+  const { args, claudeArgs } = splitClaudeArgs(argv);
   const token = readTerminalToken();
   if (!token) return 1;
   let spec;
@@ -1441,6 +1726,10 @@ async function runDispatchStartCli(argv) {
   const hasGroup = args.some(a => a === '--group' || a.startsWith('--group='));
   const group = hasGroup ? getArgValue(args, 'group') || '' : null;
   if (hasGroup && !group.trim()) return usageError(COMMANDS.dispatch.verbs.start, '--group needs a group name, path or id');
+  const child = args.includes('--child');
+  if (child === hasGroup) return usageError(COMMANDS.dispatch.verbs.start, 'Pass one of --child (part of your work) or --group <g> (separate work)');
+  const parent = process.env.CLAUDE_CODE_SESSION_ID || null;
+  if (child && !parent) return usageError(COMMANDS.dispatch.verbs.start, '--child runs only inside a Claude Code session; pass --group <g>');
   const worktree = args.includes('--worktree') ? getArgValue(args, 'worktree') || true : false;
   const hasTaskList = args.some(a => a === '--task-list' || a.startsWith('--task-list='));
   const ownList = process.env.CLAUDE_CODE_TASK_LIST_ID || process.env.CLAUDE_CODE_SESSION_ID;
@@ -1456,19 +1745,45 @@ async function runDispatchStartCli(argv) {
     worktree,
     taskList,
     group,
+    child,
     claudeArgs,
-    parent: process.env.CLAUDE_CODE_SESSION_ID || null,
+    parent,
   };
   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 session ${out.session} in ${out.cwd}${out.group ? ` [${out.group}${out.transient ? ', transient' : ''}]` : ''}`);
+    else console.log(`Started session ${out.session} in ${out.cwd}${child ? ' [child]' : ''}${out.group ? ` [${out.group}${out.transient ? ', transient' : ''}]` : ''}`);
     if (out.groupError) console.error(`Not grouped: ${out.groupError}`);
     return 0;
   } catch (e) { reportCliError(e); return 1; }
 }
 
+async function runNewCli(argv) {
+  const { args, claudeArgs } = splitClaudeArgs(argv);
+  const { names, valueFlags } = flagSpec(COMMANDS.new);
+  const unknown = args.find(a => a.startsWith('--') && !names.includes(a.split('=')[0]));
+  if (unknown) return usageError(COMMANDS.new, `Unknown flag ${unknown}; put claude's own flags after --`);
+  const words = positionals(args, valueFlags);
+  const token = readTerminalToken();
+  if (!token) return 1;
+  const body = {
+    cwd: canonicalDir(getArgValue(args, 'cwd') || '.'),
+    prompt: words.join(' '),
+    name: getArgValue(args, 'name'),
+    model: getArgValue(args, 'model'),
+    claudeArgs,
+    show: true,
+  };
+  try {
+    const out = await cliPostJson('/api/terminal/start', body, 'Start', { 'x-terminal-token': token });
+    if (!out) return 1;
+    if (args.includes('--json')) console.log(JSON.stringify(out, null, 2));
+    else console.log(`Started session ${out.session} in ${out.cwd}; it shows on the board.`);
+    return 0;
+  } catch (e) { reportCliError(e); return 1; }
+}
+
 async function fetchDispatches(all) {
   const q = new URLSearchParams();
   if (!all && process.env.CLAUDE_CODE_SESSION_ID) q.set('parent', process.env.CLAUDE_CODE_SESSION_ID);
@@ -1555,4 +1870,4 @@ async function runSkillsGetCli(args) {
   return 0;
 }
 
-module.exports = { runCli, topHelp, COMMANDS, SERVER_FLAGS, AGENT_ID_RE };
+module.exports = { runCli, topHelp, COMMANDS, SERVER_FLAGS, AGENT_ID_RE, FLAG_KEY, flagSpec, splitClaudeArgs };

package/hub-app.json

@@ -5,6 +5,11 @@
   "icon": "columns",
   "run": { "entry": "server.js", "defaultPort": 3541 },
   "publishes": ["session.changed"],
+  "actions": {
+    "handles": {
+      "session.open": { "params": { "session": "string" }, "mode": "message" }
+    }
+  },
   "settings": [
     {
       "key": "zenCentered",
@@ -38,6 +43,7 @@
     "projects": { "path": "/api/projects" },
     "terminal": { "liveWork": "/api/terminals" }
   },
+  "launcher": { "items": "/api/hub/launcher-items" },
   "loading": {
     "verbs": [
       "Shuffling cards…",

package/lib/addon-runner.js

@@ -0,0 +1,177 @@
+// Starts a global add-on's own server (`run` in its entry) the first time the board opens it and
+// the URL's port does not answer. The process is cck's child, so it ends with the board; under
+// the hub, `taskkill /f /t` on cck takes it too. A second board on the config dir finds the
+// port answering and starts nothing.
+
+const fs = require('node:fs');
+const net = require('node:net');
+const path = require('node:path');
+const { spawn, spawnSync } = require('node:child_process');
+const { sampleUrl } = require('./addons');
+const { portOf } = require('./panes');
+
+const MAX_STARTS = 3;
+const STARTS_WINDOW_MS = 60_000;
+const READY_MS = 20_000;
+const POLL_MS = 300;
+
+function urlPort(url) {
+  const u = new URL(url);
+  return { host: u.hostname.replace(/^\[|\]$/g, ''), port: portOf(u) };
+}
+
+const targetOf = (entry) => urlPort(sampleUrl(entry.url));
+
+const exited = (child) => child.exitCode !== null || child.signalCode !== null;
+
+function portAnswers({ host, port }, timeoutMs = 500) {
+  return new Promise((resolve) => {
+    const socket = net.connect({ host, port });
+    const done = (ok) => {
+      socket.destroy();
+      resolve(ok);
+    };
+    socket.setTimeout(timeoutMs, () => done(false));
+    socket.once('connect', () => done(true));
+    socket.once('error', () => done(false));
+  });
+}
+
+// Sync only on exit, where nothing async runs; else taskkill would hold the event loop for its run.
+function killTree(child, sync = false) {
+  if (exited(child)) return;
+  if (process.platform !== 'win32') {
+    // The shell's own group: SIGTERM to the shell alone leaves the server it started running.
+    try {
+      process.kill(-child.pid, 'SIGTERM');
+    } catch {
+      child.kill('SIGTERM');
+    }
+    return;
+  }
+  const args = ['/f', '/t', '/pid', String(child.pid)];
+  const opts = { windowsHide: true, stdio: 'ignore' };
+  if (sync) spawnSync('taskkill', args, opts);
+  else spawn('taskkill', args, opts).once('error', () => {});
+}
+
+/**
+ * @param {object} o
+ * @param {string} o.logDir one `<id>.log` per add-on, rewritten on each start
+ * @param {(target: {host: string, port: number}) => Promise<boolean>} [o.probe]
+ */
+function createAddonRunner({ logDir, probe = portAnswers, now = Date.now }) {
+  const byId = new Map();
+  const logPath = (id) => path.join(logDir, `${id}.log`);
+
+  async function waitReady(target, child) {
+    const until = now() + READY_MS;
+    while (now() < until) {
+      if (exited(child)) return false;
+      if (await probe(target)) return true;
+      await new Promise((r) => setTimeout(r, POLL_MS));
+    }
+    return false;
+  }
+
+  async function start(entry, target, state) {
+    const t = now();
+    state.starts = state.starts.filter((s) => t - s < STARTS_WINDOW_MS);
+    if (state.starts.length >= MAX_STARTS) {
+      return { state: 'failed', error: `Started ${MAX_STARTS} times in a minute; see the log`, log: logPath(entry.id) };
+    }
+    state.starts.push(t);
+    fs.mkdirSync(logDir, { recursive: true });
+    const fd = fs.openSync(logPath(entry.id), 'w');
+    let child;
+    try {
+      child = spawn(entry.run, {
+        shell: true,
+        detached: process.platform !== 'win32',
+        cwd: entry.cwd || undefined,
+        env: { ...process.env, PORT: String(target.port) },
+        stdio: ['ignore', fd, fd],
+        windowsHide: true,
+      });
+    } catch (e) {
+      return { state: 'failed', error: e.message, log: logPath(entry.id) };
+    } finally {
+      fs.closeSync(fd);
+    }
+    child.once('error', () => {});
+    state.child = child;
+    state.started = entry;
+    if (await waitReady(target, child)) return { state: 'up' };
+    const gone = exited(child);
+    killTree(child);
+    return { state: 'failed', error: gone ? `Exited with code ${child.exitCode}` : `No answer on port ${target.port} in ${READY_MS / 1000} s`, log: logPath(entry.id) };
+  }
+
+  // One start at a time per add-on: a second open while it starts waits for the same answer.
+  async function ensure(entry) {
+    if (!entry.run) return { state: 'none' };
+    const target = targetOf(entry);
+    if (!byId.has(entry.id)) byId.set(entry.id, { starts: [], child: null, pending: null });
+    const state = byId.get(entry.id);
+    if (state.pending) return state.pending;
+    state.pending = probe(target)
+      .then((up) => (up ? { state: 'up' } : start(entry, target, state)))
+      .finally(() => {
+        state.pending = null;
+      });
+    return state.pending;
+  }
+
+  function ownChild(id) {
+    const child = byId.get(id)?.child;
+    return child && !exited(child) ? child : null;
+  }
+
+  // 'running' (this board's child, or `external`: another process answers the port) or 'stopped'.
+  async function status(entry) {
+    if (ownChild(entry.id)) return 'running';
+    return (await probe(targetOf(entry))) ? 'external' : 'stopped';
+  }
+
+  // Kills this board's child and starts it again. A server this board did not start is left alone.
+  async function restart(entry) {
+    const child = ownChild(entry.id);
+    if (child) {
+      await new Promise((resolve) => {
+        child.once('exit', resolve);
+        killTree(child);
+      });
+    } else if ((await status(entry)) === 'external') {
+      return { state: 'external', error: 'Its server was not started by this board, so the board cannot restart it' };
+    }
+    const target = targetOf(entry);
+    const until = now() + READY_MS;
+    while (now() < until && (await probe(target))) await new Promise((r) => setTimeout(r, POLL_MS));
+    return ensure(entry);
+  }
+
+  function stop(id) {
+    const state = byId.get(id);
+    if (state?.child) killTree(state.child);
+    byId.delete(id);
+    fs.rmSync(logPath(id), { force: true });
+  }
+
+  // After another process changed addons.json: stops each server whose entry is gone or now starts
+  // another way, so a removed add-on lets go of its folder and the next open runs the new command.
+  function retain(entries) {
+    for (const [id, state] of byId) {
+      const e = entries.find((x) => x.id === id);
+      const was = state.started;
+      if (!e || (was && (e.run !== was.run || e.cwd !== was.cwd || e.url !== was.url))) stop(id);
+    }
+  }
+
+  function shutdown() {
+    for (const state of byId.values()) if (state.child) killTree(state.child, true);
+  }
+
+  return { ensure, status, restart, stop, retain, shutdown };
+}
+
+module.exports = { createAddonRunner, urlPort };