claude-code-hub 0.34.0 → 0.36.0

package/README.md

@@ -55,6 +55,8 @@ Without hooks you still get the task board, but no agent activity or live indica
 | `Ctrl+M`         | Open Memory Diagnoser for current session (Kanban) |
 | `Ctrl+Alt+Right` | Switch to next tool     |
 | `Ctrl+Alt+Left`  | Switch to previous tool |
+| `Ctrl+Alt+P`     | Switch project          |
+| `Ctrl+Alt+W`     | Switch Claude config dir (`CLAUDE_CONFIG_DIR`); restarts the sub-apps |
 
 ## How It Works
 
@@ -77,6 +79,7 @@ The hub server spawns both sub-apps as child processes, each on its own port. A
 --kanban-port <n>       Kanban port (default: 3541)
 --cost-port <n>         Cost port (default: 3543)
 --memory-port <n>       Memory Diagnoser port (default: 3544)
+--pool-size <n>         Config dirs kept running after a switch (default: 3)
 --open                  Auto-open browser
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-hub",
-  "version": "0.34.0",
+  "version": "0.36.0",
   "description": "Unified hub for Claude Code tools — Marketplace + Kanban in one PWA",
   "main": "server.js",
   "bin": {
@@ -37,10 +37,10 @@
   },
   "homepage": "https://github.com/NikiforovAll/claude-code-hub#readme",
   "dependencies": {
-    "claude-code-cost": "^0.20.0",
-    "claude-code-kanban": "^4.23.2",
-    "claude-code-marketplace": "^0.15.0",
-    "claude-code-memory-explorer": "^0.12.0",
+    "claude-code-cost": "^0.22.0",
+    "claude-code-kanban": "^4.25.0",
+    "claude-code-marketplace": "^0.17.0",
+    "claude-code-memory-explorer": "^0.14.0",
     "express": "^4.21.0",
     "open": "^10.1.0"
   },

package/public/app.js

@@ -10,7 +10,16 @@ const themeState = loadThemeState();
 // hub-theme: starting unset means there is nothing to race against each sub-app's own
 // project self-restore on boot. Once set it never returns to null.
 let projectState = null;
-const palette = { open: false, projects: [], rows: [], sel: 0, query: '' };
+// mode: 'project' (Ctrl+Alt+P) or 'configDir' (Ctrl+Alt+W). One widget, two row sources.
+const palette = {
+  open: false,
+  mode: 'project',
+  projects: [],
+  configDirs: { dirs: [], active: null },
+  rows: [],
+  sel: 0,
+  query: '',
+};
 
 function loadThemeState() {
   try {
@@ -20,8 +29,14 @@ function loadThemeState() {
   }
 }
 
+function osTheme() {
+  return window.matchMedia('(prefers-color-scheme: light)').matches ? 'light' : 'dark';
+}
+
+// Sub-apps disagree on their first-run default (marketplace follows the OS, the rest start dark),
+// so an unset theme resolves to the OS preference here and reaches every iframe on load.
 function themeMessage() {
-  return { type: 'hub:theme', theme: themeState.theme, colorTheme: themeState.colorTheme };
+  return { type: 'hub:theme', theme: themeState.theme ?? osTheme(), colorTheme: themeState.colorTheme };
 }
 
 // {<themeId>: {dark, light}} from /api/config, which derives it from scripts/themes.json — the same
@@ -32,8 +47,7 @@ let themeAccents = {};
 // Paints the palette — the hub's only themed surface — in the active theme. The hub relays
 // hub:theme to the sub-apps; this is what makes it apply to the hub's own chrome too.
 function applyHubTheme() {
-  // themeState.theme is unset until a sub-app pushes one, so fall back to the OS preference.
-  const mode = themeState.theme ?? (window.matchMedia('(prefers-color-scheme: light)').matches ? 'light' : 'dark');
+  const mode = themeState.theme ?? osTheme();
   document.documentElement.classList.toggle('light', mode === 'light');
   const pair = themeAccents[themeState.colorTheme];
   if (pair) document.documentElement.style.setProperty('--accent', pair[mode]);
@@ -105,10 +119,9 @@ async function init() {
   applyHubTheme();
   const res = await fetch('/api/config');
   const config = await res.json();
-  apps = config.apps;
+  setApps(config.apps);
   themeAccents = config.themeAccents ?? {};
   applyHubTheme();
-  allowedOrigins = new Set(Object.values(apps).map((a) => new URL(a.url).origin));
   buildIframes();
   switchTab(Object.keys(apps)[0]);
   listenMessages();
@@ -117,6 +130,31 @@ async function init() {
   registerSW();
 }
 
+function setApps(next) {
+  apps = next;
+  allowedOrigins = new Set(Object.values(apps).map((a) => new URL(a.url).origin));
+}
+
+// After a config-dir switch every child is a new process, possibly on a new port. Reloading each
+// iframe from scratch also drops the sub-apps' in-memory project state, which belonged to the old
+// dir; the hub's own projectState is cleared for the same reason.
+function reloadIframes() {
+  loadedApps.clear();
+  projectState = null;
+  // Assigning src navigates even when the URL is unchanged.
+  for (const [id, iframe] of Object.entries(iframes)) iframe.src = apps[id].url;
+}
+
+function showLoading(text = '') {
+  document.getElementById('loading-text').textContent = text;
+  document.getElementById('loading-overlay').classList.remove('fade-out');
+}
+
+function hideLoading() {
+  document.getElementById('loading-text').textContent = '';
+  document.getElementById('loading-overlay').classList.add('fade-out');
+}
+
 function buildIframes() {
   const container = document.getElementById('iframe-container');
   for (const [id, cfg] of Object.entries(apps)) {
@@ -140,30 +178,23 @@ function switchTab(appId) {
     postActiveTo(id);
   }
 
-  const overlay = document.getElementById('loading-overlay');
-  if (!loadedApps.has(appId)) {
-    overlay.classList.remove('fade-out');
-  } else {
-    overlay.classList.add('fade-out');
-  }
+  if (loadedApps.has(appId)) hideLoading();
+  else showLoading();
 
   iframes[appId]?.focus();
 }
 
 function onIframeLoad(appId) {
   loadedApps.add(appId);
-  if (appId === activeApp) {
-    document.getElementById('loading-overlay').classList.add('fade-out');
-  }
-  if (themeState.theme || themeState.colorTheme) {
-    postTo(appId, themeMessage());
-  }
+  if (appId === activeApp) hideLoading();
+  postTo(appId, themeMessage());
   postProjectTo(appId);
   postActiveTo(appId);
   // Posted twice: the shims gate their origin check on window.__HUB__, which they populate from
   // an async /hub-config fetch that resolves after this load event, so the first post can be
   // dropped. Safe to repeat — every shim's apply is idempotent.
   setTimeout(() => {
+    postTo(appId, themeMessage());
     postProjectTo(appId);
     postActiveTo(appId);
   }, 400);
@@ -207,9 +238,12 @@ function handleForwardedKey(d) {
   }
   if (d.key === 'ArrowLeft') cycleTab(-1);
   else if (d.key === 'ArrowRight') cycleTab(1);
-  else if (d.key.toLowerCase() === 'p') togglePalette();
+  else if (PALETTE_KEYS[d.key.toLowerCase()]) togglePalette(PALETTE_KEYS[d.key.toLowerCase()]);
 }
 
+// Ctrl+Alt+<letter> bindings. Sub-app shims forward every letter, so this is the one keymap.
+const PALETTE_KEYS = { p: 'project', w: 'configDir' };
+
 function cycleTab(delta) {
   const ids = Object.keys(apps);
   const idx = ids.indexOf(activeApp);
@@ -225,9 +259,9 @@ function switchByIndex(idx) {
 function listenKeys() {
   document.addEventListener('keydown', (e) => {
     // Matches both cases: with Ctrl+Alt held, some layouts report AltGr-shifted characters.
-    if (e.ctrlKey && e.altKey && !e.shiftKey && !e.metaKey && e.key.toLowerCase() === 'p') {
+    if (e.ctrlKey && e.altKey && !e.shiftKey && !e.metaKey && PALETTE_KEYS[e.key.toLowerCase()]) {
       e.preventDefault();
-      togglePalette();
+      togglePalette(PALETTE_KEYS[e.key.toLowerCase()]);
       return;
     }
     // While the palette is open the input owns the keyboard — don't let tab shortcuts fire
@@ -264,12 +298,7 @@ function listenKeys() {
 }
 
 async function loadProjects() {
-  const res = await fetch('/api/projects');
-  if (!res.ok) {
-    const body = await res.json().catch(() => ({}));
-    throw new Error(body.error || `HTTP ${res.status}`);
-  }
-  const list = await res.json();
+  const list = await sendJson('GET', '/api/projects');
   // kanban sorts alphabetically; a picker wants most-recently-touched first.
   palette.projects = list
     .map((p) => ({
@@ -294,8 +323,7 @@ function subseq(text, q) {
 // hits above parent-path hits. Tier ties fall back to the recency order set in loadProjects.
 // Returns {p, tier} so the renderer can mark the field that actually explains the match instead of
 // re-deriving it.
-function projectRows(projects, query) {
-  const q = query.trim().toLowerCase();
+function projectRows(projects, q) {
   if (!q) return projects.slice(0, 100).map((p) => ({ p, tier: 0 }));
   const tierOf = (p) => {
     if (p.name.toLowerCase().includes(q)) return 0;
@@ -368,20 +396,101 @@ function relAge(ts) {
   return `${Math.round(m / 1440)}d`;
 }
 
+async function loadConfigDirs() {
+  palette.configDirs = await sendJson('GET', '/api/config-dirs');
+}
+
+// Removes a dir from the hub's list only; nothing on disk changes. The server refuses the active
+// dir, whose row has no remove button.
+async function removeConfigDir(dirPath) {
+  try {
+    palette.configDirs = await sendJson('DELETE', '/api/config-dirs', { path: dirPath });
+  } catch (err) {
+    console.warn('remove config dir failed:', err.message);
+    return;
+  }
+  if (palette.open && palette.mode === 'configDir') renderPalette();
+}
+
+// `typed` is the trimmed query, `q` its lowercase form for matching.
+const PALETTE_MODES = {
+  project: {
+    placeholder: 'Search projects or type a path...',
+    label: 'Switch project',
+    empty: 'No matching project',
+    literalLabel: 'Use literal path',
+    load: loadProjects,
+    rows(typed, q) {
+      const rows = projectRows(palette.projects, q).map((x) => ({
+        kind: 'project',
+        path: x.p.path,
+        p: x.p,
+        tier: x.tier,
+      }));
+      if (looksLikePath(typed)) rows.push({ kind: 'literal', path: typed });
+      return rows;
+    },
+    fillRow(li, row, q) {
+      // Only the field that ranked the row is marked — otherwise a one-letter query like "c"
+      // would light up the "C:" drive letter on every row. Tier 0 is a basename hit.
+      li.append(
+        markedSpan('name', row.p.name, row.tier === 0 ? q : ''),
+        markedSpan('parent', row.p.parent, row.tier === 0 ? '' : q),
+        el('span', 'age', relAge(row.p.ts)),
+      );
+    },
+    commit: commitProject,
+  },
+  configDir: {
+    placeholder: 'Pick a Claude config dir or type a path to add...',
+    label: 'Switch config dir',
+    hint: 'Enter switch · Ctrl+D remove · type a path to add',
+    empty: 'No matching config dir',
+    literalLabel: 'Add config dir',
+    load: loadConfigDirs,
+    rows(typed, q) {
+      const { dirs, active } = palette.configDirs;
+      const rows = dirs
+        .filter((d) => !q || d.toLowerCase().includes(q))
+        .map((d) => ({ kind: 'dir', path: d, active: d === active }));
+      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.
+    initialSel(rows) {
+      const active = rows.findIndex((r) => r.active);
+      if (active < 0 || rows.length < 2) return 0;
+      return (active - 1 + rows.length) % rows.length;
+    },
+    fillRow(li, row, q) {
+      li.append(markedSpan('name', row.path, q));
+      if (row.active) {
+        li.append(el('span', 'age', 'active'));
+        return;
+      }
+      const remove = el('button', 'palette-remove', '×');
+      remove.type = 'button';
+      remove.title = 'Remove from list (Ctrl+D)';
+      remove.dataset.remove = row.path;
+      li.append(remove);
+    },
+    commit: commitConfigDir,
+  },
+};
+
 function renderPalette() {
   const list = document.getElementById('palette-list');
-  const q = palette.query.trim().toLowerCase();
-  const rows = projectRows(palette.projects, palette.query).map((x) => ({
-    kind: 'project',
-    path: x.p.path,
-    p: x.p,
-    tier: x.tier,
-  }));
-  if (looksLikePath(palette.query)) rows.push({ kind: 'literal', path: palette.query.trim() });
+  const spec = PALETTE_MODES[palette.mode];
+  const typed = palette.query.trim();
+  const q = typed.toLowerCase();
+  const rows = spec.rows(typed, q);
   palette.rows = rows;
+  // sel is null until the first render that has rows: the cached list may be empty until load() lands.
+  if (palette.sel === null && rows.length > 0) palette.sel = spec.initialSel?.(rows) ?? 0;
   palette.sel = Math.min(palette.sel, Math.max(0, rows.length - 1));
   if (rows.length === 0) {
-    list.replaceChildren(el('li', 'palette-empty', 'No matching project'));
+    list.replaceChildren(el('li', 'palette-empty', spec.empty));
     return;
   }
   list.replaceChildren(
@@ -391,17 +500,8 @@ function renderPalette() {
         `palette-row${row.kind === 'literal' ? ' literal' : ''}${i === palette.sel ? ' selected' : ''}`,
       );
       li.dataset.idx = String(i);
-      if (row.kind === 'literal') {
-        li.textContent = `Use literal path -- ${row.path}`;
-      } else {
-        // Only the field that ranked the row is marked — otherwise a one-letter query like "c"
-        // would light up the "C:" drive letter on every row. Tier 0 is a basename hit.
-        li.append(
-          markedSpan('name', row.p.name, row.tier === 0 ? q : ''),
-          markedSpan('parent', row.p.parent, row.tier === 0 ? '' : q),
-          el('span', 'age', relAge(row.p.ts)),
-        );
-      }
+      if (row.kind === 'literal') li.textContent = `${spec.literalLabel} -- ${row.path}`;
+      else spec.fillRow(li, row, q);
       return li;
     }),
   );
@@ -416,17 +516,23 @@ function el(tag, className, text) {
   return node;
 }
 
-function togglePalette() {
-  if (palette.open) closePalette();
-  else openPalette();
+function togglePalette(mode) {
+  // Same shortcut again closes; the other shortcut swaps the open palette to its mode.
+  if (palette.open && palette.mode === mode) closePalette();
+  else openPalette(mode);
 }
 
-function openPalette() {
+function openPalette(mode) {
   const input = document.getElementById('palette-input');
+  const spec = PALETTE_MODES[mode];
   palette.open = true;
+  palette.mode = mode;
   palette.query = '';
-  palette.sel = 0;
+  palette.sel = null;
   input.value = '';
+  input.placeholder = spec.placeholder;
+  document.querySelector('#palette .palette-box').setAttribute('aria-label', spec.label);
+  document.getElementById('palette-hint').textContent = spec.hint ?? '';
   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
@@ -435,11 +541,12 @@ function openPalette() {
   renderPalette();
   input.focus();
   // Stale-while-revalidate: the cached list renders instantly, recency refreshes when this lands.
-  loadProjects()
+  spec
+    .load()
     .then(() => {
-      if (palette.open) renderPalette();
+      if (palette.open && palette.mode === mode) renderPalette();
     })
-    .catch((err) => console.warn('project list unavailable:', err.message));
+    .catch((err) => console.warn(`${mode} list unavailable:`, err.message));
 }
 
 function closePalette() {
@@ -462,7 +569,10 @@ function movePaletteSel(delta) {
 
 async function commitPalette() {
   const row = palette.rows[palette.sel];
-  if (!row) return;
+  if (row) await PALETTE_MODES[palette.mode].commit(row);
+}
+
+async function commitProject(row) {
   // List rows broadcast verbatim: kanban handed us this exact string and matches it with strict
   // ===. Only a typed path needs normalizing.
   const absPath = row.kind === 'project' ? row.path : await resolveTypedPath(row.path);
@@ -471,22 +581,64 @@ async function commitPalette() {
   setProject(absPath);
 }
 
-// Returns the real on-disk path, or null when it can't be resolved (the palette stays open).
-async function resolveTypedPath(typed) {
+async function sendJson(method, url, body) {
+  const res = await fetch(url, {
+    method,
+    headers: body === undefined ? undefined : { 'Content-Type': 'application/json' },
+    body: body === undefined ? undefined : JSON.stringify(body),
+  });
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) throw new Error(data.error || `HTTP ${res.status}`);
+  return data;
+}
+
+// Disables the palette input for the duration of a request so Enter can't fire twice.
+async function withPaletteBusy(fn) {
   const input = document.getElementById('palette-input');
   input.disabled = true;
   try {
-    const res = await fetch(`/api/resolve-path?path=${encodeURIComponent(typed)}`);
-    const data = await res.json().catch(() => ({}));
-    if (res.ok) return data.path;
-    console.warn('resolve-path failed:', data.error || res.status);
-  } catch (err) {
-    console.warn('resolve-path failed:', err.message);
+    return await fn();
   } finally {
     input.disabled = false;
     if (palette.open) input.focus();
   }
-  return null;
+}
+
+async function commitConfigDir(row) {
+  let target = row.path;
+  if (row.kind === 'literal') {
+    try {
+      target = (await withPaletteBusy(() => sendJson('POST', '/api/config-dirs', { path: row.path }))).path;
+    } catch (err) {
+      console.warn('add config dir failed:', err.message);
+      return;
+    }
+  }
+  closePalette();
+  // The server would no-op too, but the client would still reload every iframe.
+  if (target === palette.configDirs.active) return;
+  showLoading(`Switching to ${target}...`);
+  try {
+    setApps((await sendJson('POST', '/api/config-dirs/activate', { path: target })).apps);
+    // The palette renders from this cache before its refetch lands, and initialSel keys off it.
+    palette.configDirs.active = target;
+    reloadIframes();
+  } catch (err) {
+    console.warn('config dir switch failed:', err.message);
+    hideLoading();
+  }
+}
+
+// Returns the real on-disk path, or null when it can't be resolved (the palette stays open).
+function resolveTypedPath(typed) {
+  return withPaletteBusy(async () => {
+    try {
+      return (await sendJson('GET', `/api/resolve-path?path=${encodeURIComponent(typed)}`)).path;
+    } catch (err) {
+      console.warn('resolve-path failed:', err.message);
+      return null;
+    }
+  });
 }
 
 function bindPalette() {
@@ -510,9 +662,21 @@ function bindPalette() {
     } else if (e.key === 'ArrowUp' || (e.key === 'Tab' && e.shiftKey)) {
       e.preventDefault();
       movePaletteSel(-1);
+    } else if (e.ctrlKey && !e.altKey && !e.shiftKey && !e.metaKey && e.key.toLowerCase() === 'd') {
+      // Ctrl+D would otherwise bookmark the page in Chrome and Firefox.
+      e.preventDefault();
+      const row = palette.rows[palette.sel];
+      if (row?.kind === 'dir') removeConfigDir(row.path);
     }
   });
   document.getElementById('palette-list').addEventListener('click', (e) => {
+    const remove = e.target.closest('.palette-remove');
+    if (remove) {
+      e.stopPropagation();
+      removeConfigDir(remove.dataset.remove);
+      document.getElementById('palette-input').focus();
+      return;
+    }
     const li = e.target.closest('.palette-row');
     if (!li) return;
     palette.sel = Number(li.dataset.idx);

package/public/index.html

@@ -67,6 +67,8 @@
       position: absolute;
       top: 0; left: 0; right: 0; bottom: 0;
       display: flex;
+      flex-direction: column;
+      gap: 14px;
       align-items: center;
       justify-content: center;
       background: var(--bg);
@@ -90,7 +92,15 @@
 
     @keyframes spin { to { transform: rotate(360deg); } }
 
-    /* Project switcher palette — the hub's only chrome, summoned with Ctrl+Alt+P. */
+    .loading-text {
+      color: var(--text-dim);
+      font: 13px/1.4 ui-monospace, SFMono-Regular, Menlo, monospace;
+    }
+
+    .loading-text:empty { display: none; }
+
+    /* Switcher palette — the hub's only chrome. Ctrl+Alt+P for projects, Ctrl+Alt+W for Claude
+       config dirs. */
     .palette {
       position: fixed;
       inset: 0;
@@ -183,12 +193,41 @@
       padding: 10px 14px;
       color: var(--text-dim);
     }
+
+    /* Mirrors memory's picker: the remove control is hidden until the row is hovered or selected. */
+    .palette-row .palette-remove {
+      margin-left: auto;
+      padding: 0 6px;
+      border: none;
+      background: transparent;
+      color: var(--text-dim);
+      font: inherit;
+      font-size: 16px;
+      line-height: 1;
+      cursor: pointer;
+      opacity: 0;
+    }
+
+    .palette-row:hover .palette-remove,
+    .palette-row.selected .palette-remove { opacity: 1; }
+
+    .palette-row .palette-remove:hover { color: #e5484d; }
+
+    .palette-hint {
+      padding: 8px 14px;
+      border-top: 1px solid var(--border);
+      color: var(--text-dim);
+      font-size: 12px;
+    }
+
+    .palette-hint:empty { display: none; }
   </style>
 </head>
 <body>
   <div class="iframe-container" id="iframe-container">
     <div class="loading-overlay" id="loading-overlay">
       <div class="spinner"></div>
+      <div class="loading-text" id="loading-text"></div>
     </div>
   </div>
 
@@ -197,6 +236,7 @@
       <input class="palette-input" id="palette-input" type="text" spellcheck="false"
              autocomplete="off" placeholder="Search projects or type a path...">
       <ul class="palette-list" id="palette-list" role="listbox"></ul>
+      <div class="palette-hint" id="palette-hint"></div>
     </div>
   </div>
 

package/server.js

@@ -3,6 +3,8 @@
 const { spawn } = require('child_process');
 const express = require('express');
 const fs = require('fs');
+const http = require('http');
+const os = require('os');
 const path = require('path');
 const { createNetGuard } = require('./lib/net-guard');
 
@@ -20,20 +22,87 @@ const KANBAN_PORT = parseInt(getArg('kanban-port') || '3541', 10);
 const COST_PORT = parseInt(getArg('cost-port') || '3543', 10);
 const MEMORY_PORT = parseInt(getArg('memory-port') || '3544', 10);
 
-const children = [];
-const actualPorts = { marketplace: MARKETPLACE_PORT, kanban: KANBAN_PORT, cost: COST_PORT, memory: MEMORY_PORT };
+const POOL_SIZE = Math.max(1, parseInt(getArg('pool-size') || '3', 10));
+const DEFAULT_PORTS = { marketplace: MARKETPLACE_PORT, kanban: KANBAN_PORT, cost: COST_PORT, memory: MEMORY_PORT };
+
+// One child set per config dir, kept alive after a switch so switching back is instant. Map
+// insertion order doubles as LRU: activating a dir re-inserts it at the end.
+const pools = new Map();
+
+function activePool() {
+  return pools.get(hubConfig.activeConfigDir);
+}
+
+// Every sub-app resolves CLAUDE_CONFIG_DIR once at startup into a module constant, so switching
+// the dir means restarting the children. Kept on the server, not in the browser: the dir has to
+// be known before the first spawn, and the hub already has one localStorage key to reason about.
+const HUB_CONFIG_FILE = path.join(os.homedir(), '.claude-hub', 'config.json');
+
+function expandHome(p) {
+  return p.startsWith('~') ? p.replace('~', os.homedir()) : p;
+}
+
+// Real on-disk spelling (true casing, native separators). One dir is one list entry and one child
+// pool whichever way it was typed. Throws when the path does not exist.
+function canonicalDir(p) {
+  return fs.realpathSync.native(path.resolve(expandHome(p)));
+}
+
+function loadHubConfig() {
+  const canonical = (p) => {
+    try {
+      return canonicalDir(p);
+    } catch {
+      return expandHome(p);
+    }
+  };
+  const fallback = canonical(
+    process.env.CLAUDE_CONFIG_DIR || process.env.CLAUDE_DIR || path.join(os.homedir(), '.claude'),
+  );
+  let raw = '';
+  let saved = {};
+  try {
+    raw = fs.readFileSync(HUB_CONFIG_FILE, 'utf8');
+    saved = JSON.parse(raw);
+  } catch {}
+  const savedDirs = Array.isArray(saved.configDirs) ? saved.configDirs.filter((d) => typeof d === 'string') : [];
+  const dirs = [...new Set(savedDirs.map(canonical))];
+  if (!dirs.includes(fallback)) dirs.unshift(fallback);
+  const savedActive = typeof saved.activeConfigDir === 'string' ? canonical(saved.activeConfigDir) : null;
+  const active = dirs.includes(savedActive) ? savedActive : fallback;
+  const config = { configDirs: dirs, activeConfigDir: active };
+  // Configs saved before canonicalization can hold one dir under two spellings; persist the merge.
+  if (serializeConfig(config) !== raw) writeHubConfig(config);
+  return config;
+}
+
+function serializeConfig(config) {
+  return `${JSON.stringify(config, null, 2)}\n`;
+}
+
+function writeHubConfig(config) {
+  fs.mkdirSync(path.dirname(HUB_CONFIG_FILE), { recursive: true });
+  fs.writeFileSync(HUB_CONFIG_FILE, serializeConfig(config));
+}
+
+function saveHubConfig() {
+  writeHubConfig(hubConfig);
+}
+
+const hubConfig = loadHubConfig();
 
 // Created before spawnApp so the same host/allowed-hosts decision reaches the
 // children. Without that propagation, `--host 0.0.0.0` would expose the hub shell
 // while every iframe 403'd on its own Host check.
 const net = createNetGuard({ appName: 'Claude Code Hub' });
 
-function spawnApp(name, cmd, args, envPort) {
+function spawnApp(pool, name, cmd, args) {
   const child = spawn(cmd, args, {
     cwd: __dirname,
     env: {
       ...process.env,
-      PORT: String(envPort),
+      PORT: '0',
+      CLAUDE_CONFIG_DIR: pool.dir,
       CLAUDE_HUB: '1',
       HUB_URL: `http://localhost:${HUB_PORT}`,
       HOST: net.BIND_HOST,
@@ -43,6 +112,10 @@ function spawnApp(name, cmd, args, envPort) {
   });
 
   let stdoutBuf = '';
+  let markReady;
+  child.ready = new Promise((resolve) => {
+    markReady = resolve;
+  });
   child.stdout.on('data', (d) => {
     stdoutBuf += d.toString();
     let nl;
@@ -51,19 +124,25 @@ function spawnApp(name, cmd, args, envPort) {
       stdoutBuf = stdoutBuf.slice(nl + 1);
       process.stdout.write(`[${name}] ${line}`);
       const match = line.match(/running at http:\/\/localhost:(\d+)/i);
-      if (match) actualPorts[name] = parseInt(match[1], 10);
+      if (match) {
+        pool.ports[name] = parseInt(match[1], 10);
+        markReady();
+      }
     }
   });
   child.stderr.on('data', (d) => process.stderr.write(`[${name}] ${d}`));
-  child.on('exit', (code) => console.log(`[${name}] exited (code ${code})`));
+  child.on('exit', (code) => {
+    console.log(`[${name}] exited (code ${code})`);
+    markReady();
+  });
 
-  children.push(child);
+  pool.children.push(child);
   return child;
 }
 
-function killAll() {
-  for (const child of children) {
-    if (child.killed) continue;
+function killPool(pool) {
+  for (const child of pool.children) {
+    if (child.exitCode !== null || child.killed) continue;
     if (process.platform === 'win32') {
       spawn('taskkill', ['/pid', String(child.pid), '/f', '/t'], { stdio: 'ignore' });
     } else {
@@ -72,6 +151,47 @@ function killAll() {
   }
 }
 
+function killAll() {
+  for (const pool of pools.values()) killPool(pool);
+}
+
+function withTimeout(promise, ms) {
+  let timer;
+  const gate = new Promise((resolve) => {
+    timer = setTimeout(resolve, ms);
+  });
+  return Promise.race([promise, gate]).finally(() => clearTimeout(timer));
+}
+
+// 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
+// the caller can hand the client URLs that are actually live.
+async function ensurePool(dir) {
+  let pool = pools.get(dir);
+  if (pool) {
+    pools.delete(dir);
+    pools.set(dir, pool);
+    return pool.ready;
+  }
+  while (pools.size >= POOL_SIZE) {
+    const oldestDir = pools.keys().next().value;
+    console.log(`Evicting children for ${oldestDir}`);
+    dropPool(oldestDir);
+  }
+  pool = { dir, children: [], ports: {} };
+  pools.set(dir, pool);
+  spawnChildren(pool);
+  pool.ready = withTimeout(Promise.all(pool.children.map((c) => c.ready)), 20000).then(() => pool);
+  return pool.ready;
+}
+
+function dropPool(dir) {
+  const pool = pools.get(dir);
+  if (!pool) return;
+  pools.delete(dir);
+  killPool(pool);
+}
+
 function shutdown() {
   killAll();
   process.exit(0);
@@ -115,12 +235,86 @@ const memoryPath = resolveApp('memory', 'claude-code-memory-explorer');
 const HDR_BYTES = 65536;
 const NODE_HDR = `--max-http-header-size=${HDR_BYTES}`;
 
-spawnApp('marketplace', process.execPath, [NODE_HDR, marketplacePath, `--port=${MARKETPLACE_PORT}`], MARKETPLACE_PORT);
-spawnApp('kanban', process.execPath, [NODE_HDR, kanbanPath], KANBAN_PORT);
-spawnApp('cost', process.execPath, [NODE_HDR, costPath, `--port=${COST_PORT}`], COST_PORT);
-spawnApp('memory', process.execPath, [NODE_HDR, memoryPath, `--port=${MEMORY_PORT}`], MEMORY_PORT);
+// Children bind ephemeral ports; the public ports below belong to the hub's proxies. Browser
+// localStorage is keyed by origin, so the sub-app origin has to stay put across switches or the
+// user loses pins and filters every time the active set changes.
+function spawnChildren(pool) {
+  spawnApp(pool, 'marketplace', process.execPath, [NODE_HDR, marketplacePath]);
+  spawnApp(pool, 'kanban', process.execPath, [NODE_HDR, kanbanPath]);
+  spawnApp(pool, 'cost', process.execPath, [NODE_HDR, costPath]);
+  spawnApp(pool, 'memory', process.execPath, [NODE_HDR, memoryPath]);
+}
+
+const publicPorts = { ...DEFAULT_PORTS };
+
+function rewriteOrigin(origin, publicPort, childPort) {
+  try {
+    const u = new URL(origin);
+    if (Number(u.port) !== publicPort) return origin;
+    u.port = String(childPort);
+    return u.origin;
+  } catch {
+    return origin;
+  }
+}
+
+const proxyAgent = new http.Agent({ keepAlive: true, maxSockets: 64 });
+
+// Host is forwarded untouched so the child's hostGuard still sees what the browser sent. Origin is
+// the one header the child cannot judge on its own: its guard compares the port to its own
+// ephemeral one, so the public-port spelling is mapped to the child's; anything else passes
+// through as-is and the child rejects it.
+function proxyHandler(name) {
+  return (req, res) => {
+    const childPort = activePool()?.ports[name];
+    if (!childPort) {
+      res.writeHead(503, { 'Retry-After': '1' });
+      res.end(`${name} is starting`);
+      return;
+    }
+    const headers = { ...req.headers };
+    if (headers.origin) headers.origin = rewriteOrigin(headers.origin, publicPorts[name], childPort);
+    const upstream = http.request(
+      { host: '127.0.0.1', port: childPort, method: req.method, path: req.url, headers, agent: proxyAgent },
+      (u) => {
+        res.writeHead(u.statusCode, u.headers);
+        u.pipe(res);
+      },
+    );
+    upstream.on('error', (err) => {
+      if (!res.headersSent) res.writeHead(502);
+      res.end(err.message);
+    });
+    res.on('close', () => upstream.destroy());
+    req.pipe(upstream);
+  };
+}
+
+function listenWithFallback(handler, port, onReady, label) {
+  const server = net.listenLoopback(handler, port, onReady, { maxHeaderSize: HDR_BYTES });
+  server.on('error', (err) => {
+    if (err.code !== 'EADDRINUSE' && err.code !== 'EACCES') throw err;
+    console.log(`${label}port ${port} in use, trying random port...`);
+    net.listenLoopback(handler, 0, onReady, { maxHeaderSize: HDR_BYTES });
+  });
+  return server;
+}
+
+for (const [name, port] of Object.entries(DEFAULT_PORTS)) {
+  listenWithFallback(
+    proxyHandler(name),
+    port,
+    (actual) => {
+      publicPorts[name] = actual;
+    },
+    `[${name}] `,
+  );
+}
+
+ensurePool(hubConfig.activeConfigDir);
 
 const app = express();
+app.use(express.json());
 
 // Mounted before the routes below, which are registered ahead of the first
 // app.use() and would otherwise bypass the guards entirely.
@@ -142,26 +336,94 @@ const themeAccents = (() => {
   }
 })();
 
+function appsConfig() {
+  return {
+    kanban: { name: 'Kanban', url: `http://localhost:${publicPorts.kanban}`, icon: 'columns' },
+    marketplace: { name: 'Marketplace', url: `http://localhost:${publicPorts.marketplace}`, icon: 'store' },
+    cost: { name: 'Cost', url: `http://localhost:${publicPorts.cost}`, icon: 'dollar-sign' },
+    memory: { name: 'Memory Diagnoser', url: `http://localhost:${publicPorts.memory}`, icon: 'database' },
+  };
+}
+
 app.get('/api/config', (_req, res) => {
-  res.json({
-    themeAccents,
-    apps: {
-      kanban: { name: 'Kanban', url: `http://localhost:${actualPorts.kanban}`, icon: 'columns' },
-      marketplace: { name: 'Marketplace', url: `http://localhost:${actualPorts.marketplace}`, icon: 'store' },
-      cost: { name: 'Cost', url: `http://localhost:${actualPorts.cost}`, icon: 'dollar-sign' },
-      memory: { name: 'Memory Diagnoser', url: `http://localhost:${actualPorts.memory}`, icon: 'database' },
-    },
-  });
+  res.json({ themeAccents, apps: appsConfig() });
+});
+
+app.get('/api/config-dirs', (_req, res) => {
+  res.setHeader('Cache-Control', 'no-store');
+  res.json({ dirs: hubConfig.configDirs, active: hubConfig.activeConfigDir });
+});
+
+// Normalizes a typed path to its real on-disk form (true casing, native separators) so cck's
+// strict === project match and cost's abs->encoded transform both hit, and so the config-dir list
+// holds one spelling per dir.
+function resolveDir(input) {
+  if (typeof input !== 'string' || !input.trim()) return { error: 'path is required', status: 400 };
+  let resolved;
+  try {
+    resolved = canonicalDir(input.trim());
+  } catch {
+    return { error: 'Path not found', status: 404 };
+  }
+  if (!fs.statSync(resolved).isDirectory()) return { error: 'Not a directory', status: 400 };
+  return { path: resolved };
+}
+
+app.post('/api/config-dirs', (req, res) => {
+  const r = resolveDir(req.body?.path);
+  if (r.error) {
+    res.status(r.status).json({ error: r.error });
+    return;
+  }
+  if (!hubConfig.configDirs.includes(r.path)) {
+    hubConfig.configDirs.push(r.path);
+    saveHubConfig();
+  }
+  res.json({ path: r.path });
+});
+
+app.delete('/api/config-dirs', (req, res) => {
+  const raw = typeof req.body?.path === 'string' ? req.body.path : '';
+  const target = resolveDir(raw).path ?? raw;
+  if (target === hubConfig.activeConfigDir) {
+    res.status(400).json({ error: 'Cannot remove the active config dir' });
+    return;
+  }
+  hubConfig.configDirs = hubConfig.configDirs.filter((d) => d !== target);
+  saveHubConfig();
+  dropPool(target);
+  res.json({ dirs: hubConfig.configDirs, active: hubConfig.activeConfigDir });
+});
+
+// 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 : '';
+  if (!hubConfig.configDirs.includes(target)) {
+    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({ apps: appsConfig() });
 });
 
 // Project list for the switcher palette, proxied from kanban — it is the only sub-app that
-// enumerates projects. actualPorts is read per request because kanban's real port is only
-// known once its banner has been scraped (see spawnApp).
+// enumerates projects. The port is read per request because kanban's real port is only known
+// once its banner has been scraped (see spawnApp).
 app.get('/api/projects', async (_req, res) => {
   res.setHeader('Cache-Control', 'no-store');
+  const kanbanPort = activePool()?.ports.kanban;
+  if (!kanbanPort) {
+    res.status(503).json({ error: 'kanban is starting' });
+    return;
+  }
   try {
     // 127.0.0.1, not localhost — Node's verbatim DNS ordering tries ::1 first on Windows.
-    const upstream = await fetch(`http://127.0.0.1:${actualPorts.kanban}/api/projects`, {
+    const upstream = await fetch(`http://127.0.0.1:${kanbanPort}/api/projects`, {
       signal: AbortSignal.timeout(4000),
     });
     if (!upstream.ok) {
@@ -175,28 +437,12 @@ app.get('/api/projects', async (_req, res) => {
   }
 });
 
-// Normalizes a typed path to its real on-disk form (true casing, native separators) so cck's
-// strict === project match and cost's abs->encoded transform both hit. List-picked paths skip
-// this: they are byte-exact copies of what kanban reported.
+// List-picked project paths skip this: they are byte-exact copies of what kanban reported.
 app.get('/api/resolve-path', (req, res) => {
   res.setHeader('Cache-Control', 'no-store');
-  const input = typeof req.query.path === 'string' ? req.query.path.trim() : '';
-  if (!input) {
-    res.status(400).json({ error: 'path is required' });
-    return;
-  }
-  let resolved;
-  try {
-    resolved = fs.realpathSync.native(path.resolve(input));
-  } catch {
-    res.status(404).json({ error: 'Path not found' });
-    return;
-  }
-  if (!fs.statSync(resolved).isDirectory()) {
-    res.status(400).json({ error: 'Not a directory' });
-    return;
-  }
-  res.json({ path: resolved });
+  const r = resolveDir(req.query.path);
+  if (r.error) res.status(r.status).json({ error: r.error });
+  else res.json({ path: r.path });
 });
 
 app.use(express.static(path.join(__dirname, 'public')));
@@ -208,7 +454,7 @@ const onReady = (actual) => {
   }
 };
 
-const server = net.listenLoopback(app, HUB_PORT, onReady, { maxHeaderSize: HDR_BYTES });
+listenWithFallback(app, HUB_PORT, onReady, '');
 
 function printBanner(port) {
   console.log(`Claude Code Hub running at http://localhost:${port}`);
@@ -216,12 +462,3 @@ function printBanner(port) {
   if (warning) console.log(warning);
   console.log('Type "q" or "exit" to stop the server');
 }
-
-server.on('error', (err) => {
-  if (err.code === 'EADDRINUSE' || err.code === 'EACCES') {
-    console.log(`Port ${HUB_PORT} in use, trying random port...`);
-    net.listenLoopback(app, 0, onReady, { maxHeaderSize: HDR_BYTES });
-  } else {
-    throw err;
-  }
-});