claude-code-hub 1.13.0 → 1.15.0

package/lib/apps.js

@@ -24,7 +24,8 @@ const isObject = (x) => typeof x === 'object' && x !== null && !Array.isArray(x)
 // unlisted ones follow in default order, so an app added in a later release shows up without an edit.
 // An entry with a `path` runs the app in that folder: a fork in place of a built-in app, or a new app.
 // A relative `path` is resolved against `base`, the folder of config.json.
-function selectApps(entries = [], base = process.cwd()) {
+// `includeOff` keeps the apps with `enabled: false` and gives every app `enabled`.
+function selectApps(entries = [], base = process.cwd(), { includeOff = false } = {}) {
   const listed = entries.filter((e) => typeof e?.id === 'string');
   const entryOf = (id) => listed.find((e) => e.id === id);
   const pathOf = (id) => {
@@ -37,11 +38,12 @@ function selectApps(entries = [], base = process.cwd()) {
   const order = new Set([...listed.map((e) => e.id), ...APPS.map((a) => a.id)]);
   const apps = [...order]
     .map(byId)
-    .filter((a) => a && !off.has(a.id))
+    .filter((a) => a && (includeOff || !off.has(a.id)))
     .map((a) => {
       const e = entryOf(a.id);
       return {
         ...a,
+        ...(includeOff && { enabled: !off.has(a.id) }),
         port: e?.port,
         path: pathOf(a.id),
         hidden: e?.hidden === true,

package/lib/ext.js

@@ -6,7 +6,7 @@ const path = require('node:path');
 const { parseArgs } = require('node:util');
 const { APPS, HUB_ROOT, ID_RE, selectApps, appRoot, readApp } = require('./apps');
 const { isContained } = require('./contain');
-const { writeConfigFile } = require('./hub-config');
+const { readConfig, writeConfigFile } = require('./hub-config');
 const { claudeEnv, hasClaude, installPlugin, reinstallPlugin, uninstallPlugin, report, run } = require('./install');
 const { pluginChecker } = require('./plugin-status');
 const { isNewer } = require('./update-check');
@@ -28,21 +28,6 @@ const USAGE = `Usage: claude-code-hub ext <command>
 const RESTART = '  Restart the hub to load the change.';
 const REGISTRY = 'https://nikiforovall.blog/claude-code-hub/extensions.json';
 
-function readConfig(hubDir) {
-  const file = path.join(hubDir, 'config.json');
-  let raw;
-  try {
-    raw = fs.readFileSync(file, 'utf8');
-  } catch (e) {
-    if (e.code === 'ENOENT') return { file, config: {} };
-    throw e;
-  }
-  try {
-    return { file, config: JSON.parse(raw) };
-  } catch (e) {
-    throw new Error(`${file}: ${e.message}`);
-  }
-}
 
 function checkRequires(ctx, { id, requires }, config) {
   if (!requires) return;

package/lib/hub-config.js

@@ -12,4 +12,21 @@ function writeConfigFile(file, config) {
   fs.writeFileSync(file, serializeConfig(config));
 }
 
-module.exports = { serializeConfig, writeConfigFile };
+// A missing file reads as {}. Bad JSON throws, so a caller does not write over a hand edit.
+function readConfig(hubDir) {
+  const file = path.join(hubDir, 'config.json');
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch (e) {
+    if (e.code === 'ENOENT') return { file, config: {} };
+    throw e;
+  }
+  try {
+    return { file, config: JSON.parse(raw) };
+  } catch (e) {
+    throw new Error(`${file}: ${e.message}`);
+  }
+}
+
+module.exports = { readConfig, serializeConfig, writeConfigFile };

package/lib/keymap.js

@@ -6,6 +6,7 @@ const HUB_ACTIONS = [
   'hub.projectPicker',
   'hub.configDirPicker',
   'hub.appLauncher',
+  'hub.settings',
   'hub.prevApp',
   'hub.nextApp',
   'hub.appByNumber',
@@ -15,7 +16,7 @@ const PATTERN_ACTIONS = new Set(['hub.appByNumber']);
 const MODS = ['ctrl', 'alt', 'shift', 'meta'];
 
 // A combo name as the SDK's comboOf() gives it (protocol section 8), with one modifier at least.
-const COMBO_RE = /^(?=(?:ctrl|alt|shift|meta)\+)(?:ctrl\+)?(?:alt\+)?(?:shift\+)?(?:meta\+)?(?:[a-z1-9]|[A-Z][A-Za-z0-9]+)$/;
+const COMBO_RE = /^(?=(?:ctrl|alt|shift|meta)\+)(?:ctrl\+)?(?:alt\+)?(?:shift\+)?(?:meta\+)?(?:[a-z1-9,]|[A-Z][A-Za-z0-9]+)$/;
 
 // "Ctrl+Alt+O" → "ctrl+alt+o", the form comboOf() gives. Null when the text cannot name a combo.
 function normalizeCombo(text) {

package/lib/settings.js

@@ -0,0 +1,93 @@
+'use strict';
+
+const { selectApps } = require('./apps');
+
+const CONFIG_DIR_SWITCH = ['palette', 'swap'];
+const DEFAULT_POOL_SIZE = 3;
+const MAX_POOL_SIZE = 8;
+const APP_STATES = ['shown', 'hidden', 'off'];
+
+const validPoolSize = (n) => Number.isInteger(n) && n >= 1 && n <= MAX_POOL_SIZE;
+
+function configDirSwitch(saved) {
+  return CONFIG_DIR_SWITCH.includes(saved?.configDirSwitch) ? saved.configDirSwitch : 'palette';
+}
+
+function poolSize(saved, flag) {
+  if (flag !== null && flag !== undefined) return Math.max(1, parseInt(flag, 10) || DEFAULT_POOL_SIZE);
+  return validPoolSize(saved?.poolSize) ? saved.poolSize : DEFAULT_POOL_SIZE;
+}
+
+// The keys the running hub applies at once, so it keeps them in memory.
+const LIVE_SETTINGS = ['configDirSwitch', 'poolSize'];
+
+function copyLive(from, to) {
+  for (const k of LIVE_SETTINGS) if (from[k] !== undefined) to[k] = from[k];
+}
+
+// Every app the `apps` list can turn on, in tab order, with the state its entry gives it.
+function appSettings(entries = [], base) {
+  return selectApps(entries, base, { includeOff: true }).apps.map((a) => ({
+    ...a,
+    state: !a.enabled ? 'off' : a.hidden ? 'hidden' : 'shown',
+  }));
+}
+
+// What the running hub would do differently after a restart: the apps it spawns and how.
+function appsShape(apps) {
+  return JSON.stringify(apps.filter((a) => a.state !== 'off').map((a) => [a.id, a.state, a.deferredStart]));
+}
+
+// `saved` is config.json as on disk. Returns the new config, or {error}. Only the keys the
+// patch names change; an app entry keeps its other fields (port, path, source).
+function applySettings(saved, patch, base) {
+  if (!patch || typeof patch !== 'object') return { error: 'body must be an object' };
+  const next = { ...saved };
+  if (patch.configDirSwitch !== undefined) {
+    if (!CONFIG_DIR_SWITCH.includes(patch.configDirSwitch))
+      return { error: `configDirSwitch must be one of ${CONFIG_DIR_SWITCH.join(', ')}` };
+    next.configDirSwitch = patch.configDirSwitch;
+  }
+  if (patch.poolSize !== undefined) {
+    if (!validPoolSize(patch.poolSize)) return { error: `poolSize must be an integer from 1 to ${MAX_POOL_SIZE}` };
+    next.poolSize = patch.poolSize;
+  }
+  if (patch.app !== undefined) {
+    const { id, state, deferredStart } = patch.app ?? {};
+    const current = appSettings(saved.apps, base);
+    if (!current.some((a) => a.id === id)) return { error: `Unknown app "${id}"` };
+    if (state !== undefined && !APP_STATES.includes(state))
+      return { error: `state must be one of ${APP_STATES.join(', ')}` };
+    if (deferredStart !== undefined && typeof deferredStart !== 'boolean')
+      return { error: 'deferredStart must be a boolean' };
+    if (state === 'off' && current.every((a) => a.id === id || a.state === 'off'))
+      return { error: 'At least one app must stay on' };
+    let entries = Array.isArray(saved.apps) ? [...saved.apps] : [];
+    // Listed apps come first, so a new entry appended at the end would move its tab. Listing
+    // every app in its current order keeps the order.
+    if (!entries.some((e) => e?.id === id)) {
+      const others = entries.filter((e) => !current.some((a) => a.id === e?.id));
+      entries = [...current.map((a) => entries.find((e) => e?.id === a.id) ?? { id: a.id }), ...others];
+    }
+    const i = entries.findIndex((e) => e?.id === id);
+    const entry = { ...entries[i] };
+    if (state !== undefined) {
+      entry.enabled = state !== 'off';
+      entry.hidden = state === 'hidden';
+    }
+    if (deferredStart !== undefined) entry.deferredStart = deferredStart;
+    entries[i] = entry;
+    next.apps = entries;
+  }
+  return { config: next };
+}
+
+module.exports = {
+  copyLive,
+  MAX_POOL_SIZE,
+  appSettings,
+  appsShape,
+  applySettings,
+  configDirSwitch,
+  poolSize,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-hub",
-  "version": "1.13.0",
+  "version": "1.15.0",
   "description": "Unified hub for Claude Code tools — Marketplace + Kanban in one PWA",
   "main": "server.js",
   "bin": {
@@ -47,7 +47,7 @@
   "homepage": "https://github.com/NikiforovAll/claude-code-hub#readme",
   "dependencies": {
     "claude-code-cost": "1.3.2",
-    "claude-code-kanban": "7.9.0",
+    "claude-code-kanban": "7.11.0",
     "claude-code-marketplace": "1.5.2",
     "claude-code-memory-explorer": "1.3.2",
     "express": "^4.21.0",

package/plugin/plugins/claude-code-hub/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-hub",
-  "version": "0.2.9",
+  "version": "0.2.10",
   "description": "Claude Code Hub integration: a skill to build on and extend the hub, with links to its docs, the extension mechanism and custom themes",
   "author": {
     "name": "NikiforovAll"

package/plugin/plugins/claude-code-hub/skills/hub-builder/references/keys.md

@@ -35,13 +35,14 @@ Ctrl+Alt+O opens the project palette, Ctrl+Alt+H and Ctrl+Alt+L move between too
 | `hub.projectPicker` | `ctrl+alt+p` | `ctrl+alt+p` |
 | `hub.configDirPicker` | `ctrl+alt+w` | `ctrl+alt+w` |
 | `hub.appLauncher` | `ctrl+alt+a` | `ctrl+alt+a` |
+| `hub.settings` | `ctrl+,` | `ctrl+,` |
 | `hub.prevApp` | `ctrl+alt+ArrowLeft` | `ctrl+alt+ArrowLeft` |
 | `hub.nextApp` | `ctrl+alt+ArrowRight` | `ctrl+alt+ArrowRight` |
 | `hub.appByNumber` | `alt+{n}` | `ctrl+alt+{n}` |
 
 ## Rules
 
-- **Form.** One or more of `ctrl`, `alt`, `shift`, `meta`, then one key, joined by `+`. The key is a letter, a digit 1 to 9, or a `KeyboardEvent.key` name (`ArrowUp`, `F2`, `PageDown`). On macOS `alt` is Option and `meta` is Command. Modifiers and letters take any case and order (`"Alt+Ctrl+O"` reads as `ctrl+alt+o`); a key name keeps its case (`PageDown`).
+- **Form.** One or more of `ctrl`, `alt`, `shift`, `meta`, then one key, joined by `+`. The key is a letter, a digit 1 to 9, `,`, or a `KeyboardEvent.key` name (`ArrowUp`, `F2`, `PageDown`). On macOS `alt` is Option and `meta` is Command. Modifiers and letters take any case and order (`"Alt+Ctrl+O"` reads as `ctrl+alt+o`); a key name keeps its case (`PageDown`).
 - **`{n}`.** `hub.appByNumber` ends in `+{n}`, and the hub binds it for 1 to 9. It is the only action with `{n}`.
 - **`null`** leaves the action with no key.
 - **Taking a default.** A combo that is another action's default moves to the new action, and the other action has no key until it gets one: `"hub.nextApp": "ctrl+alt+a"` leaves the app launcher with no key. Say so to the user.

package/public/app.js

@@ -40,6 +40,8 @@ const missed = new Map();
 const MAX_EVENT_CHARS = 16 * 1024;
 // The config dir the hub falls back to (~/.claude). Stays out of the window title.
 let defaultConfigDir = null;
+// What Ctrl+Alt+W does: 'palette' opens the config-dir palette, 'swap' switches to the previous dir.
+let configDirSwitch = 'palette';
 // The app launcher's footer: the hub version from /api/config and its plugin from /api/apps/stats.
 const hubInfo = { version: null, plugin: null };
 // mode: 'project' (Ctrl+Alt+P), 'configDir' (Ctrl+Alt+W) or 'app' (Ctrl+Alt+A). One widget, three row sources.
@@ -47,7 +49,7 @@ const palette = {
   open: false,
   mode: 'project',
   projects: [],
-  configDirs: { dirs: [], active: null },
+  configDirs: { dirs: [], active: null, previous: null },
   rows: [],
   sel: 0,
   query: '',
@@ -68,9 +70,11 @@ function loadThemeState() {
 
 // The color theme of the active config dir, falling back to the last one picked anywhere.
 // An id the registry lacks shows as Ember everywhere, so the hub page and every app agree.
+const DEFAULT_COLOR_THEME = 'ember';
+
 function activeColorTheme() {
   const id = themeState.colorThemes[activeConfigDir] ?? themeState.colorTheme;
-  return id && hubThemes.length && !themeVars[id] ? 'ember' : id;
+  return id && hubThemes.length && !themeVars[id] ? DEFAULT_COLOR_THEME : id;
 }
 
 function osTheme() {
@@ -85,7 +89,7 @@ function themePayload() {
 
 function themeEvent() {
   const payload = themePayload();
-  const vars = themeVars[payload.colorTheme ?? 'ember']?.[payload.theme];
+  const vars = themeVars[payload.colorTheme ?? DEFAULT_COLOR_THEME]?.[payload.theme];
   return vars ? { ...payload, vars } : payload;
 }
 
@@ -122,8 +126,10 @@ function applyHubTheme() {
   const mode = themeState.theme ?? osTheme();
   const root = document.documentElement;
   root.classList.toggle('light', mode === 'light');
-  const key = `${activeColorTheme()}/${mode}`;
-  const core = themeVars[activeColorTheme()]?.[mode];
+  // No app has named a theme yet: paint the one every app starts with.
+  const theme = activeColorTheme() ?? DEFAULT_COLOR_THEME;
+  const key = `${theme}/${mode}`;
+  const core = themeVars[theme]?.[mode];
   let vars = core && Object.fromEntries(Object.entries(HUB_VARS).map(([hub, name]) => [hub, core[name]]));
   try {
     if (vars) localStorage.setItem(PALETTE_KEY, JSON.stringify({ key, vars }));
@@ -273,6 +279,7 @@ async function init() {
   setApps(config.apps);
   defaultConfigDir = config.defaultConfigDir ?? null;
   activeConfigDir = config.activeConfigDir ?? null;
+  configDirSwitch = config.configDirSwitch ?? 'palette';
   applyTitle(config.activeConfigDir);
   themeVars = config.themeVars ?? {};
   hubThemes = config.themes ?? [];
@@ -285,6 +292,7 @@ async function init() {
   listenMessages();
   listenKeys();
   bindPalette();
+  bindSettings();
   registerSW();
   bindErrorToast();
   showUpdateToast();
@@ -710,8 +718,14 @@ function handleForwardedKey(d) {
 function hubActions() {
   return [
     { id: 'hub.projectPicker', combo: 'ctrl+alt+p', run: () => togglePalette('project'), inPalette: true },
-    { id: 'hub.configDirPicker', combo: 'ctrl+alt+w', run: () => togglePalette('configDir'), inPalette: true },
+    {
+      id: 'hub.configDirPicker',
+      combo: 'ctrl+alt+w',
+      run: () => (configDirSwitch === 'swap' ? swapConfigDir() : togglePalette('configDir')),
+      inPalette: true,
+    },
     { id: 'hub.appLauncher', combo: 'ctrl+alt+a', run: () => togglePalette('app'), inPalette: true },
+    { id: 'hub.settings', combo: 'ctrl+,', run: () => toggleSettings(), inPalette: true },
     { id: 'hub.prevApp', combo: 'ctrl+alt+ArrowLeft', run: () => cycleTab(-1) },
     { id: 'hub.nextApp', combo: 'ctrl+alt+ArrowRight', run: () => cycleTab(1) },
     {
@@ -784,13 +798,14 @@ function listenKeys() {
       binding.run();
       return;
     }
-    // While the palette is open the input owns the keyboard — don't let tab shortcuts fire
-    // mid-path (Alt+digit especially, since Windows paths contain digits). Escape still closes:
-    // bound here as well as on the input so it works wherever focus landed in the hub document.
-    if (palette.open) {
+    // While the palette or the settings modal is open, its input or buttons own the keyboard — don't
+    // let tab shortcuts fire mid-path (Alt+digit especially, since Windows paths contain digits).
+    // Escape still closes: bound here as well as on the input so it works wherever focus landed in
+    // the hub document.
+    if (openOverlay) {
       if (e.key === 'Escape') {
         e.preventDefault();
-        closePalette();
+        openOverlay.close();
       }
       return;
     }
@@ -1174,9 +1189,11 @@ const PALETTE_MODES = {
       if (looksLikePath(typed) && !dirs.some((d) => d.toLowerCase() === q)) rows.push({ kind: 'literal', path: typed });
       return rows;
     },
-    // Enter on the default row must switch, so the cursor lands on the dir before the active one,
-    // wrapping. With two dirs the palette then behaves like a toggle.
+    // Enter on the default row must switch, so the cursor lands on the previous dir, else on the
+    // dir before the active one, wrapping. With two dirs the palette then behaves like a toggle.
     initialSel(rows) {
+      const previous = rows.findIndex((r) => r.path === palette.configDirs.previous);
+      if (previous >= 0) return previous;
       const active = rows.findIndex((r) => r.active);
       if (active < 0 || rows.length < 2) return 0;
       return (active - 1 + rows.length) % rows.length;
@@ -1250,6 +1267,225 @@ const PALETTE_MODES = {
   },
 };
 
+// The hub settings modal (Ctrl+,). Each change is saved at once; data is the last /api/settings answer.
+const settingsModal = { open: false, data: null, error: null, busy: false };
+
+const SWITCH_CHOICES = [
+  ['palette', 'Open the list', 'Opens the config-dir list. Pick a dir, or type a path to add one.'],
+  [
+    'swap',
+    'Swap to last dir',
+    'Switches straight to the dir you used before, with no list. With one dir only, it opens the list.',
+  ],
+];
+const SHOW_CHOICES = [
+  ['shown', 'Tab'],
+  ['hidden', 'Launcher only'],
+  ['off', 'Off'],
+];
+const START_CHOICES = [
+  [false, 'With hub'],
+  [true, 'On demand'],
+];
+
+function toggleSettings() {
+  if (settingsModal.open) closeSettings();
+  else openSettings();
+}
+
+async function openSettings() {
+  settingsModal.open = true;
+  settingsModal.error = null;
+  showOverlay('settings', closeSettings);
+  renderSettings();
+  document.querySelector('#settings .settings-box').focus();
+  try {
+    settingsModal.data = await sendJson('GET', '/api/settings');
+  } catch (err) {
+    settingsModal.error = err.message;
+  }
+  if (settingsModal.open) renderSettings();
+}
+
+function closeSettings() {
+  settingsModal.open = false;
+  hideOverlay('settings');
+}
+
+async function saveSetting(patch) {
+  if (settingsModal.busy) return;
+  settingsModal.busy = true;
+  try {
+    settingsModal.data = await sendJson('POST', '/api/settings', patch);
+    settingsModal.error = null;
+    configDirSwitch = settingsModal.data.configDirSwitch;
+  } catch (err) {
+    settingsModal.error = err.message;
+  } finally {
+    settingsModal.busy = false;
+  }
+  if (settingsModal.open) renderSettings();
+}
+
+// A row of buttons that acts as one radio group: Tab reaches the checked one, ← and → change it.
+function segmented(name, choices, current, onPick, disabledOf = () => null) {
+  const group = el('span', 'seg');
+  group.setAttribute('role', 'radiogroup');
+  group.setAttribute('aria-label', name);
+  for (const [value, label] of choices) {
+    const btn = el('button', value === current ? 'on' : '', label);
+    btn.type = 'button';
+    btn.setAttribute('role', 'radio');
+    btn.setAttribute('aria-checked', String(value === current));
+    btn.tabIndex = value === current ? 0 : -1;
+    const why = disabledOf(value);
+    if (why) {
+      btn.disabled = true;
+      btn.title = why;
+    }
+    btn.addEventListener('click', () => value !== current && onPick(value));
+    group.append(btn);
+  }
+  return group;
+}
+
+function settingRow(label, control, help) {
+  const row = el('div', 'set-row');
+  row.append(typeof label === 'string' ? el('span', 'set-label', label) : label, control);
+  if (help) row.append(el('span', 'set-help', help));
+  return row;
+}
+
+function renderSettings() {
+  const body = document.getElementById('settings-body');
+  const foot = document.getElementById('settings-foot');
+  const s = settingsModal.data;
+  const focusKey = document.activeElement?.closest?.('[data-focus]')?.dataset.focus;
+  if (!s) {
+    body.replaceChildren(el('div', 'set-help', settingsModal.error ?? 'Loading…'));
+    foot.replaceChildren();
+    return;
+  }
+
+  const dirs = el('section', 'set-sec');
+  dirs.append(el('h4', '', 'Config dirs'));
+  const key = actionKeys()['hub.configDirPicker'];
+  const label = el('span', 'set-label');
+  if (key) label.append(kbd(comboLabel(key)), ' does');
+  else label.textContent = 'Config-dir key does';
+  const sw = SWITCH_CHOICES.find(([v]) => v === s.configDirSwitch);
+  const switchSeg = segmented('Config-dir key', SWITCH_CHOICES, s.configDirSwitch, (v) =>
+    saveSetting({ configDirSwitch: v }),
+  );
+  switchSeg.dataset.focus = 'switch';
+  dirs.append(settingRow(label, switchSeg, sw[2]));
+
+  const step = el('span', 'step');
+  const stepBtn = (text, delta, aria) => {
+    const b = el('button', '', text);
+    b.type = 'button';
+    b.setAttribute('aria-label', aria);
+    const n = s.poolSize + delta;
+    b.disabled = s.poolSizeFlag || n < 1 || n > s.maxPoolSize;
+    b.dataset.focus = `pool${delta}`;
+    b.addEventListener('click', () => saveSetting({ poolSize: n }));
+    return b;
+  };
+  step.append(stepBtn('−', -1, 'Fewer'), el('b', '', String(s.poolSize)), stepBtn('+', 1, 'More'), ' dirs');
+  const poolHelp = s.poolSizeFlag
+    ? 'Set by --pool-size for this run.'
+    : s.poolSize === 1
+      ? 'Only the active dir runs its apps. Every switch waits a few seconds while the apps start.'
+      : `The ${s.poolSize} dirs you used last keep their apps running, so going back to them is instant. Each one runs its own copy of every app. Others start again when you open them (a few seconds).`;
+  dirs.append(settingRow('Instant switch-back', step, poolHelp));
+
+  const manage = el('button', '', 'Manage…');
+  manage.type = 'button';
+  manage.dataset.focus = 'manage';
+  manage.addEventListener('click', () => openPalette('configDir'));
+  dirs.append(settingRow('Config dirs', manage));
+
+  const appsSec = el('section', 'set-sec');
+  appsSec.append(el('h4', '', 'Apps'));
+  const table = el('table', 'set-apps');
+  const head = el('tr', '');
+  head.append(el('th', '', 'App'), el('th', '', 'Show'), el('th', '', 'Start'));
+  table.append(head);
+  const onCount = s.apps.filter((a) => a.state !== 'off').length;
+  for (const a of s.apps) {
+    const tr = el('tr', '');
+    const show = segmented(
+      `Show ${a.name}`,
+      SHOW_CHOICES,
+      a.state,
+      (v) => saveSetting({ app: { id: a.id, state: v } }),
+      (v) => (v === 'off' && a.state !== 'off' && onCount === 1 ? 'At least one app must stay on' : null),
+    );
+    show.dataset.focus = `show:${a.id}`;
+    const start = segmented(
+      `Start ${a.name}`,
+      START_CHOICES,
+      a.deferredStart,
+      (v) => saveSetting({ app: { id: a.id, deferredStart: v } }),
+      () => (a.state === 'off' ? 'The app is off' : null),
+    );
+    start.dataset.focus = `start:${a.id}`;
+    const showTd = el('td', '');
+    showTd.append(show);
+    const startTd = el('td', '');
+    startTd.append(start);
+    tr.append(el('td', '', a.name), showTd, startTd);
+    table.append(tr);
+  }
+  appsSec.append(
+    table,
+    el(
+      'span',
+      'set-help',
+      '“Launcher only” keeps the app running but gives it no tab or number key; open it from the app launcher. “On demand” starts it the first time you open it.',
+    ),
+  );
+  body.replaceChildren(dirs, appsSec);
+
+  let status = el('span', '', 'Saved as you change it');
+  if (settingsModal.error) status = el('span', 'set-error', settingsModal.error);
+  else if (s.restartNeeded) status = el('span', 'set-restart', 'Restart the hub to apply app changes');
+  const keys = el('span', 'set-keys');
+  keys.append(kbd('Tab'), ' move · ', kbd('←'), kbd('→'), ' change');
+  foot.replaceChildren(status, keys);
+
+  // A save redraws the modal, so put focus back on the control that had it.
+  if (focusKey) {
+    const target = body.querySelector(`[data-focus="${CSS.escape(focusKey)}"]`);
+    // A radio group gets its checked button; a button that became disabled hands focus to its neighbour.
+    const focusable = target?.matches('button:not(:disabled)')
+      ? target
+      : (target?.querySelector('[aria-checked="true"]:not(:disabled)') ??
+        target?.parentElement.querySelector('button:not(:disabled)'));
+    (focusable ?? document.querySelector('#settings .settings-box')).focus();
+  }
+}
+
+function kbd(text) {
+  return el('kbd', '', text);
+}
+
+function bindSettings() {
+  const overlay = document.getElementById('settings');
+  overlay.addEventListener('mousedown', (e) => {
+    if (e.target === overlay) closeSettings();
+  });
+  overlay.addEventListener('keydown', (e) => {
+    if (e.key !== 'ArrowLeft' && e.key !== 'ArrowRight') return;
+    const group = e.target.closest('[role="radiogroup"]');
+    if (!group) return;
+    e.preventDefault();
+    const radios = [...group.querySelectorAll('[role="radio"]:not(:disabled)')];
+    const i = radios.indexOf(e.target);
+    radios[i + (e.key === 'ArrowRight' ? 1 : -1)]?.click();
+  });
+}
+
 function renderPalette() {
   const list = document.getElementById('palette-list');
   const spec = PALETTE_MODES[palette.mode];
@@ -1306,11 +1542,7 @@ function openPalette(mode) {
   input.placeholder = spec.placeholder;
   document.querySelector('#palette .palette-box').setAttribute('aria-label', spec.label);
   drawPaletteHint();
-  document.getElementById('palette').hidden = false;
-  // Ctrl+Alt+P usually arrives forwarded from a focused iframe. Without inert the sub-app can keep
-  // or take focus back, and then Escape is handled inside it — the palette stays open and only the
-  // sub-app's own focus visibly changes.
-  setIframesInert(true);
+  showOverlay('palette', closePalette);
   renderPalette();
   input.focus();
   // Stale-while-revalidate: the cached list renders instantly, recency refreshes when this lands.
@@ -1328,7 +1560,25 @@ function openPalette(mode) {
 
 function closePalette() {
   palette.open = false;
-  document.getElementById('palette').hidden = true;
+  hideOverlay('palette');
+}
+
+// The palette and the settings modal: one is open at a time, and Escape closes it.
+let openOverlay = null;
+
+function showOverlay(id, close) {
+  if (openOverlay && openOverlay.id !== id) openOverlay.close();
+  openOverlay = { id, close };
+  document.getElementById(id).hidden = false;
+  // Hub keys usually arrive forwarded from a focused iframe. Without inert the sub-app can keep
+  // or take focus back, and then Escape is handled inside it — the overlay stays open and only the
+  // sub-app's own focus visibly changes.
+  setIframesInert(true);
+}
+
+function hideOverlay(id) {
+  if (openOverlay?.id === id) openOverlay = null;
+  document.getElementById(id).hidden = true;
   setIframesInert(false);
   iframes[activeApp]?.focus();
 }
@@ -1394,19 +1644,39 @@ async function commitConfigDir(row) {
   closePalette();
   // The server would no-op too, but the client would still reload every iframe.
   if (target === palette.configDirs.active) return;
+  await switchConfigDir(() => sendJson('POST', '/api/config-dirs/activate', { path: target }));
+}
+
+// The previous dir, with no palette. With none (one dir only) it opens the palette to add one.
+let swapping = false;
+async function swapConfigDir() {
+  if (swapping) return;
+  swapping = true;
+  openOverlay?.close();
+  try {
+    await switchConfigDir(() => sendJson('POST', '/api/config-dirs/swap'));
+  } finally {
+    swapping = false;
+  }
+}
+
+async function switchConfigDir(request) {
   showLoading();
   try {
-    setApps((await sendJson('POST', '/api/config-dirs/activate', { path: target })).apps);
+    const { apps: list, active, previous } = await request();
+    setApps(list);
     // The palette renders from this cache before its refetch lands, and initialSel keys off it.
-    palette.configDirs.active = target;
-    activeConfigDir = target;
-    applyTitle(target);
+    palette.configDirs.previous = previous;
+    palette.configDirs.active = active;
+    activeConfigDir = active;
+    applyTitle(active);
     // Each iframe gets the new dir's color theme from its load handler; this repaints the palette.
     applyHubTheme();
     reloadIframes();
   } catch (err) {
-    showErrorToast('Could not switch config dir', err);
     hideLoading();
+    if (err.status === 409) openPalette('configDir');
+    else showErrorToast('Could not switch config dir', err);
   }
 }
 

package/public/index.html

@@ -238,8 +238,15 @@
     /* Bar over the neutral hover background, no accent tint: the faintest theme accents
        (monokai light #c08a00, vitesse light #1c6b48) barely register as a tint, but read
        clearly as a 2px bar. */
-    .palette-row.selected {
+    .palette-row.selected,
+    .set-row:focus-within,
+    .set-apps tr:focus-within td {
       background: var(--surface-hover);
+    }
+
+    .palette-row.selected,
+    .set-row:focus-within,
+    .set-apps tr:focus-within td:first-child {
       box-shadow: inset 2px 0 0 var(--accent);
     }
 
@@ -380,6 +387,118 @@
 
     .palette-hint:empty { display: none; }
 
+    /* Built from the palette's parts so the two read as one: same box, row padding, selected-row
+       bar (on the row that holds focus) and footer. Controls follow cck's quiet ones: an accent
+       tint for the chosen option, not a solid fill. */
+    .settings-box {
+      max-height: 76vh;
+      overflow-y: auto;
+      color: var(--text);
+      font-size: 13px;
+      outline: none;
+    }
+
+    .settings-bar {
+      display: flex;
+      align-items: center;
+      gap: 10px;
+      padding: 12px 14px;
+      border-bottom: 1px solid var(--border);
+    }
+
+    .settings-bar h3 { font-size: 14px; font-weight: 600; }
+    .settings-bar kbd { margin-left: auto; }
+
+    .set-sec { padding: 6px 0; border-bottom: 1px solid var(--border); }
+    .set-sec:last-child { border-bottom: none; }
+
+    .set-sec h4 {
+      padding: 6px 14px 4px;
+      font-size: 11px;
+      font-weight: 600;
+      letter-spacing: 0.05em;
+      text-transform: uppercase;
+      color: var(--text-dim);
+    }
+
+    .set-row {
+      display: grid;
+      grid-template-columns: 1fr auto;
+      gap: 2px 12px;
+      align-items: center;
+      padding: 8px 14px;
+    }
+
+
+    .set-label { font-weight: 600; }
+    .set-help { grid-column: 1 / -1; color: var(--text-dim); font-size: 12px; }
+    .set-sec > .set-help { display: block; padding: 6px 14px 8px; }
+    #settings-body > .set-help { display: block; padding: 12px 14px; }
+
+    .settings-box button {
+      padding: 2px 8px;
+      border: 1px solid var(--border);
+      border-radius: 4px;
+      background: transparent;
+      color: var(--text-dim);
+      font: inherit;
+      font-size: 12px;
+      cursor: pointer;
+    }
+
+    .settings-box button:hover:not(:disabled) { color: var(--text); }
+    .settings-box button:disabled { opacity: 0.4; cursor: default; }
+
+    .settings-box button:focus-visible {
+      outline: none;
+      box-shadow: 0 0 0 2px color-mix(in srgb, var(--accent) 45%, transparent);
+    }
+
+    .seg {
+      display: inline-flex;
+      gap: 2px;
+      padding: 2px;
+      border: 1px solid var(--border);
+      border-radius: 6px;
+      white-space: nowrap;
+    }
+
+    .seg button { border-color: transparent; }
+
+    .seg button.on {
+      background: color-mix(in srgb, var(--accent) 18%, transparent);
+      color: var(--text);
+      font-weight: 600;
+    }
+
+    .step { display: inline-flex; align-items: center; gap: 8px; color: var(--text-dim); }
+    .step button { width: 24px; padding: 2px 0; }
+    .step b { min-width: 12px; text-align: center; color: var(--text); font-variant-numeric: tabular-nums; }
+
+    .set-apps { width: 100%; border-collapse: collapse; }
+    .set-apps th, .set-apps td { padding: 5px 6px; text-align: left; white-space: nowrap; }
+    .set-apps th:first-child, .set-apps td:first-child { padding-left: 14px; width: 100%; }
+    .set-apps th:last-child, .set-apps td:last-child { padding-right: 14px; }
+    .set-apps th { color: var(--text-dim); font-size: 11px; font-weight: 400; }
+    .set-apps td:first-child { font-weight: 600; }
+
+    .settings-foot { display: flex; gap: 12px; }
+
+    .settings-foot .set-keys { margin-left: auto; }
+    .set-restart { color: var(--warn); }
+    .set-restart::before { content: '●'; margin-right: 6px; }
+    .set-error { color: #e5484d; }
+
+    .settings-box kbd {
+      padding: 0 4px;
+      border: 1px solid var(--border);
+      border-bottom-width: 2px;
+      border-radius: 4px;
+      background: var(--bg);
+      font: 11px ui-monospace, SFMono-Regular, Menlo, monospace;
+      color: var(--text-dim);
+    }
+
     .update-toast {
       position: fixed;
       right: 16px;
@@ -495,6 +614,14 @@
     </div>
   </div>
 
+  <div class="palette" id="settings" hidden>
+    <div class="palette-box settings-box" role="dialog" aria-modal="true" aria-labelledby="settings-title" tabindex="-1">
+      <div class="settings-bar"><h3 id="settings-title">Hub settings</h3><kbd>Esc</kbd></div>
+      <div id="settings-body"></div>
+      <div class="palette-hint settings-foot" id="settings-foot"></div>
+    </div>
+  </div>
+
   <div class="update-toast" id="update-toast" role="status" hidden>
     <div class="update-toast-body">
       <div class="update-toast-title">Claude Code Hub <span id="update-latest"></span> is available</div>

package/server.js

@@ -9,7 +9,7 @@ const tcp = require('net');
 const os = require('os');
 const path = require('path');
 const { actionTable } = require('./lib/actions');
-const { selectApps, loadApp, conflicts } = require('./lib/apps');
+const { HUB_ROOT, selectApps, appRoot, loadApp, conflicts, readApp } = require('./lib/apps');
 const { userKeys } = require('./lib/keymap');
 const { stripCookie } = require('./lib/cookies');
 const { createNetGuard, KEEP_ALIVE_MS } = require('./lib/net-guard');
@@ -21,7 +21,16 @@ const { createUpdateCheck } = require('./lib/update-check');
 const { liveHub, removeRecord, writeRecord } = require('./lib/hub-record');
 const { HUB_PLUGIN } = require('./lib/install');
 const { pluginChecker } = require('./lib/plugin-status');
-const { serializeConfig, writeConfigFile } = require('./lib/hub-config');
+const { readConfig, serializeConfig, writeConfigFile } = require('./lib/hub-config');
+const {
+  appSettings,
+  appsShape,
+  applySettings,
+  configDirSwitch,
+  poolSize,
+  copyLive,
+  MAX_POOL_SIZE,
+} = require('./lib/settings');
 const { version: HUB_VERSION } = require('./package.json');
 
 function getArg(name) {
@@ -36,7 +45,7 @@ const DEFAULT_HUB_PORT = 3540;
 const HUB_PORT = parseInt(getArg('port') || process.env.PORT || DEFAULT_HUB_PORT, 10);
 let hubPort = HUB_PORT;
 
-const POOL_SIZE = Math.max(1, parseInt(getArg('pool-size') || '3', 10));
+const POOL_SIZE_FLAG = getArg('pool-size');
 const RESTART_DELAY_MS = 500;
 // A rate window, not a total: a child may die and recover all session, but one that cannot stay up
 // stops being restarted. A consecutive counter cannot express that — anything that starts at all
@@ -150,6 +159,9 @@ function resolveHubConfig() {
   if (saved.terminal && typeof saved.terminal === 'object') config.terminal = saved.terminal;
   if (Array.isArray(saved.apps)) config.apps = saved.apps;
   if (saved.keys !== undefined) config.keys = saved.keys;
+  copyLive(saved, config);
+  const savedPrevious = typeof saved.previousConfigDir === 'string' ? canonical(saved.previousConfigDir) : null;
+  if (dirs.includes(savedPrevious) && savedPrevious !== active) config.previousConfigDir = savedPrevious;
   return { config, raw, fallback };
 }
 
@@ -161,12 +173,22 @@ function writeHubConfig(config) {
 function saveHubConfig() {
   let saved = hubConfig;
   try {
-    saved = JSON.parse(fs.readFileSync(HUB_CONFIG_FILE, 'utf8'));
+    saved = readSavedConfig();
   } catch {}
-  writeHubConfig({ ...saved, configDirs: hubConfig.configDirs, activeConfigDir: hubConfig.activeConfigDir });
+  writeHubConfig({
+    ...saved,
+    configDirs: hubConfig.configDirs,
+    activeConfigDir: hubConfig.activeConfigDir,
+    previousConfigDir: hubConfig.previousConfigDir,
+  });
+}
+
+function readSavedConfig() {
+  return readConfig(path.dirname(HUB_CONFIG_FILE)).config;
 }
 
 const hubConfig = loadHubConfig();
+const currentPoolSize = () => poolSize(hubConfig, POOL_SIZE_FLAG);
 
 const { apps: selectedApps, unknown: unknownApps } = selectApps(hubConfig.apps, path.dirname(HUB_CONFIG_FILE));
 const ENABLED_APPS = selectedApps.map((a) => loadApp(a, { flagPort: getArg(`${a.id}-port`) })).filter(Boolean);
@@ -380,7 +402,7 @@ function withTimeout(promise, ms) {
 }
 
 // Returns the live pool for a dir, spawning one when absent and evicting the least recently used
-// pool past POOL_SIZE. Resolves once every child has printed its port banner (or given up), so
+// pool past the pool size. Resolves once every child has printed its port banner (or given up), so
 // the caller can hand the client URLs that are actually live.
 async function ensurePool(dir) {
   let pool = pools.get(dir);
@@ -389,7 +411,7 @@ async function ensurePool(dir) {
     pools.set(dir, pool);
     return pool.ready;
   }
-  if (pools.size >= POOL_SIZE) await evictPools(dir);
+  if (pools.size >= currentPoolSize()) await evictPools(dir);
   pool = pools.get(dir);
   if (pool) return pool.ready;
   const stopped = new Set(ENABLED_APPS.filter((a) => a.deferredStart).map((a) => a.id));
@@ -423,10 +445,10 @@ async function evictPools(keepDir) {
     const counts = await Promise.all(candidates.map(terminalCount));
     pinned = new Set(candidates.filter((_, i) => counts[i]).map((p) => p.dir));
   }
-  while (pools.size >= POOL_SIZE) {
+  while (pools.size >= currentPoolSize()) {
     const victim = [...pools.keys()].find((d) => d !== keepDir && !pinned.has(d));
     if (!victim) {
-      console.log(`Pool size ${POOL_SIZE} exceeded: every other pool has live terminals`);
+      console.log(`Pool size ${currentPoolSize()} exceeded: every other pool has live terminals`);
       return;
     }
     console.log(`Evicting children for ${victim}`);
@@ -931,13 +953,20 @@ app.get('/api/config', (_req, res) => {
     keys: USER_KEYS,
     activeConfigDir: hubConfig.activeConfigDir,
     defaultConfigDir,
+    configDirSwitch: configDirSwitch(hubConfig),
     version: HUB_VERSION,
   });
 });
 
+// The dir a swap goes to: the one active before the current one, else the other of exactly two.
+function swapTarget() {
+  const { configDirs: dirs, activeConfigDir: active, previousConfigDir: previous } = hubConfig;
+  return previous ?? (dirs.length === 2 ? dirs.find((d) => d !== active) : null);
+}
+
 app.get('/api/config-dirs', (_req, res) => {
   res.setHeader('Cache-Control', 'no-store');
-  res.json({ dirs: hubConfig.configDirs, active: hubConfig.activeConfigDir });
+  res.json({ dirs: hubConfig.configDirs, active: hubConfig.activeConfigDir, previous: swapTarget() });
 });
 
 // Normalizes a typed path to its real on-disk form (true casing, native separators) so cck's
@@ -976,11 +1005,23 @@ app.delete('/api/config-dirs', (req, res) => {
     return;
   }
   hubConfig.configDirs = hubConfig.configDirs.filter((d) => d !== target);
+  if (hubConfig.previousConfigDir === target) delete hubConfig.previousConfigDir;
   saveHubConfig();
   dropPool(target);
-  res.json({ dirs: hubConfig.configDirs, active: hubConfig.activeConfigDir });
+  res.json({ dirs: hubConfig.configDirs, active: hubConfig.activeConfigDir, previous: swapTarget() });
 });
 
+async function activateConfigDir(target) {
+  if (target !== hubConfig.activeConfigDir) {
+    console.log(`Switching CLAUDE_CONFIG_DIR -> ${target}`);
+    await ensurePool(target);
+    hubConfig.previousConfigDir = hubConfig.activeConfigDir;
+    hubConfig.activeConfigDir = target;
+    saveHubConfig();
+  }
+  return { apps: appsConfig(), active: target, previous: swapTarget() };
+}
+
 // The response carries the app URLs so the client reloads every iframe against the new set.
 app.post('/api/config-dirs/activate', async (req, res) => {
   const target = typeof req.body?.path === 'string' ? req.body.path : '';
@@ -988,13 +1029,79 @@ app.post('/api/config-dirs/activate', async (req, res) => {
     res.status(404).json({ error: 'Unknown config dir; add it first' });
     return;
   }
-  if (target !== hubConfig.activeConfigDir) {
-    console.log(`Switching CLAUDE_CONFIG_DIR -> ${target}`);
-    await ensurePool(target);
-    hubConfig.activeConfigDir = target;
-    saveHubConfig();
+  res.json(await activateConfigDir(target));
+});
+
+app.post('/api/config-dirs/swap', async (_req, res) => {
+  const target = swapTarget();
+  if (!target) {
+    res.status(409).json({ error: 'No previous config dir' });
+    return;
+  }
+  res.json(await activateConfigDir(target));
+});
+
+// Apps changes need a hub restart: the app list is read once at startup.
+const CONFIG_BASE = path.dirname(HUB_CONFIG_FILE);
+const RUNNING_APPS = appsShape(appSettings(hubConfig.apps, CONFIG_BASE));
+const appNames = new Map(ENABLED_APPS.map((a) => [a.id, a.name]));
+
+// An app that is off has no loaded manifest, so its name is read on first use.
+function appName(a) {
+  if (!appNames.has(a.id)) {
+    let name = a.id;
+    try {
+      name = readApp(appRoot(a, HUB_ROOT, require.resolve), a.id).manifest.name;
+    } catch {}
+    appNames.set(a.id, name);
+  }
+  return appNames.get(a.id);
+}
+
+function settingsView(saved) {
+  const apps = appSettings(Array.isArray(saved.apps) ? saved.apps : [], CONFIG_BASE);
+  return {
+    configDirSwitch: configDirSwitch(hubConfig),
+    poolSize: currentPoolSize(),
+    poolSizeFlag: POOL_SIZE_FLAG !== null,
+    maxPoolSize: MAX_POOL_SIZE,
+    apps: apps.map((a) => ({ id: a.id, state: a.state, deferredStart: a.deferredStart, name: appName(a) })),
+    restartNeeded: appsShape(apps) !== RUNNING_APPS,
+  };
+}
+
+function readSettingsConfig(res) {
+  try {
+    return readSavedConfig();
+  } catch (e) {
+    res.status(500).json({ error: e.message });
+    return null;
+  }
+}
+
+app.get('/api/settings', (_req, res) => {
+  const saved = readSettingsConfig(res);
+  if (!saved) return;
+  res.setHeader('Cache-Control', 'no-store');
+  res.json(settingsView(saved));
+});
+
+// Writes config.json from its copy on disk, so `ext` and hand edits made while the hub runs stay.
+app.post('/api/settings', (req, res) => {
+  if (req.body?.poolSize !== undefined && POOL_SIZE_FLAG !== null) {
+    res.status(409).json({ error: '--pool-size sets the pool size for this run' });
+    return;
+  }
+  const saved = readSettingsConfig(res);
+  if (!saved) return;
+  const r = applySettings(saved, req.body, CONFIG_BASE);
+  if (r.error) {
+    res.status(400).json({ error: r.error });
+    return;
   }
-  res.json({ apps: appsConfig() });
+  writeHubConfig(r.config);
+  copyLive(r.config, hubConfig);
+  res.json(settingsView(r.config));
 });
 
 // The stalls hit a few percent of requests, so each round sends several probes per app.