claude-code-hub 0.38.0 → 0.39.0-rc.1

package/README.md

@@ -4,85 +4,155 @@
 [![license](https://img.shields.io/npm/l/claude-code-hub)](LICENSE)
 [![npm downloads](https://img.shields.io/npm/dm/claude-code-hub)](https://www.npmjs.com/package/claude-code-hub)
 
-Unified launcher for Claude Code tools — browse plugins in **Marketplace**, track tasks in **Kanban**, monitor costs in **Cost**, and explore memory in **Memory Diagnoser**, all from a single chromeless PWA.
+One window for your Claude Code tools: Kanban, Marketplace, Cost, and Memory Diagnoser, in a single chromeless PWA that you drive from the keyboard.
 
-## Kanban:
+Website: [nikiforovall.blog/claude-code-hub](https://nikiforovall.blog/claude-code-hub/)
 
-![Kanban Screenshot](./assets/cck.png)
+## The tools
 
-## Marketplace:
-![Marketplace Screenshot](./assets/marketplace.png)
+### Kanban
 
-## Cost:
-![Cost Screenshot](./assets/cost.png)
+See tasks, sessions, and live agent activity as a board. Open a Claude Code session in the embedded terminal.
 
-## Memory Diagnoser:
-![Memory Diagnoser Screenshot](./assets/memory.png)
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="assets/kanban-dark.webp">
+  <img alt="Kanban board with sessions and tasks" src="assets/kanban-light.webp">
+</picture>
 
-## Quick Start
+### Marketplace
+
+Browse and manage Claude Code marketplace plugins.
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="assets/marketplace-dark.webp">
+  <img alt="Marketplace with the plugin list" src="assets/marketplace-light.webp">
+</picture>
+
+### Cost
+
+See what your Claude Code usage costs, per session and per project.
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="assets/cost-dark.webp">
+  <img alt="Cost dashboard with usage charts" src="assets/cost-light.webp">
+</picture>
+
+### Memory Diagnoser
+
+Explore the memory files that Claude Code loads for a project.
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="assets/memory-dark.webp">
+  <img alt="Memory Diagnoser with loaded memory files" src="assets/memory-light.webp">
+</picture>
+
+## Quick start
 
 ```bash
 npx claude-code-hub --open
 ```
 
-### From Source
+The hub starts on `http://localhost:3540` and opens the browser. To get a window with no browser UI, install the page as an app from the browser menu.
+
+### From source
 
 ```bash
 git clone --recurse-submodules https://github.com/NikiforovAll/claude-code-hub.git
 cd claude-code-hub
-npm install && npm install --prefix marketplace && npm install --prefix cck && npm install --prefix memory
+npm install && npm install --prefix marketplace && npm install --prefix cck && npm install --prefix cost && npm install --prefix memory
 npm start        # http://localhost:3540
 ```
 
-## Agent Observability (one-time setup)
+## Agent observability (one-time setup)
 
-For the full Kanban experience — agent log, live subagent tracking, waiting-for-user indicators, and context window monitoring — install the hooks:
+For the full Kanban view (agent log, live subagent tracking, waiting-for-user indicators, and context window use), install the hooks:
 
 ```bash
 npx claude-code-kanban --install
 ```
 
-Without hooks you still get the task board, but no agent activity or live indicators. See the [Kanban README](https://github.com/NikiforovAll/claude-task-viewer#getting-started) for details.
+Without the hooks you still get the task board and sessions, but no live agent activity. The hooks and status line are installed per Claude config dir, so run the command again for each dir you use. See the [Kanban docs](https://nikiforovall.blog/claude-code-kanban/) for details.
+
+## Hub token
+
+The hub page and its API need a token. Any local account can reach a loopback port, and the API carries the terminal token.
+
+- The token is in `~/.claude-hub/token`. The hub creates it on the first run and keeps it across restarts.
+- The startup banner prints the URL with the token, `http://localhost:3540/?token=…`, and `--open` uses that URL. The hub sets a cookie and then removes the token from the address bar, so later visits and the installed app need no token.
+- Without the token, the page shows a locked screen.
+- To change the token, delete the file and restart the hub.
 
-## Keyboard Shortcuts
+## Config dirs
 
-| Shortcut         | Action                  |
-| ---------------- | ----------------------- |
-| `Alt+1`          | Switch to Kanban        |
-| `Alt+2`          | Switch to Marketplace   |
-| `Alt+3`          | Switch to Cost          |
-| `Alt+4`          | Switch to Memory Diagnoser |
-| `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 |
+The hub can run the tools against more than one Claude config dir (`CLAUDE_CONFIG_DIR`), for example a work dir and a personal dir.
 
-## How It Works
+- Press <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>W</kbd> to open the config-dir palette. Pick a dir to switch to it, or type a path to add a new one. <kbd>Ctrl</kbd>+<kbd>D</kbd> removes the selected dir.
+- Each dir gets its own set of the four tools. When you switch, the hub keeps the old set running, so switching back is instant. `--pool-size` sets how many sets stay alive (default 3). When the pool is full, the hub stops the least recently used set, but not a set whose Kanban has open terminals.
+- The list and the active dir are saved in `~/.claude-hub/config.json`.
 
-The hub server spawns both sub-apps as child processes, each on its own port. A minimal shell page embeds them in iframes and switches visibility on tab change — zero UI chrome, just keyboard shortcuts.
+## Embedded terminal
 
-## Included Tools
+Under the hub, Kanban has an embedded terminal, on by default, so you can start or resume Claude Code sessions from the board. While a terminal is attached, the hub asks before it closes the window, because <kbd>Ctrl</kbd>+<kbd>W</kbd> meant for the terminal would close it.
 
-| Tool                                                                   | Submodule      | Default Port |
-| ---------------------------------------------------------------------- | -------------- | ------------ |
-| [Marketplace](https://github.com/NikiforovAll/claude-code-marketplace) | `marketplace/` | 3542         |
-| [Kanban](https://github.com/NikiforovAll/claude-task-viewer)           | `cck/`         | 3541         |
-| [Cost](https://github.com/NikiforovAll/claude-code-cost)               | `cost/`        | 3543         |
-| [Memory Diagnoser](https://github.com/NikiforovAll/claude-code-memory) | `memory/`      | 3544         |
+To turn the terminal off, start the hub with `--disable-terminal`, or add this to `~/.claude-hub/config.json`:
 
-## CLI Flags
+```json
+{
+  "terminal": { "enabled": false }
+}
+```
+
+## Keyboard shortcuts
+
+The hub has no visible UI of its own. Use these shortcuts:
+
+| Shortcut | Action |
+| --- | --- |
+| <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>→</kbd> | Next tool |
+| <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>←</kbd> | Previous tool |
+| <kbd>Alt</kbd>+<kbd>1</kbd> | Kanban |
+| <kbd>Alt</kbd>+<kbd>2</kbd> | Marketplace |
+| <kbd>Alt</kbd>+<kbd>3</kbd> | Cost |
+| <kbd>Alt</kbd>+<kbd>4</kbd> | Memory Diagnoser |
+| <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>P</kbd> | Project palette: set the project for all tools |
+| <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>W</kbd> | Config-dir palette: switch, add, or remove a config dir |
+
+In a palette, use <kbd>↑</kbd>/<kbd>↓</kbd> or <kbd>Tab</kbd> to move, <kbd>Enter</kbd> to select, and <kbd>Esc</kbd> to close.
+
+The shortcuts also work when focus is inside a tool. Kanban keeps <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>N</kbd> (new session), <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>R</kbd> (resume session), and <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>S</kbd> (previous session) for itself. From Kanban you can also jump to another tool for the selected session:
+
+| Shortcut | Action |
+| --- | --- |
+| <kbd>M</kbd> | Open Marketplace for the session's project |
+| <kbd>$</kbd> | Open Cost for the session |
+| <kbd>Ctrl</kbd>+<kbd>M</kbd> | Open Memory Diagnoser for the session's project |
+
+## CLI flags
 
 ```
 --port <n>              Hub port (default: 3540)
---marketplace-port <n>  Marketplace port (default: 3542)
 --kanban-port <n>       Kanban port (default: 3541)
+--marketplace-port <n>  Marketplace port (default: 3542)
 --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
+--pool-size <n>         Config-dir sets kept running after a switch (default: 3)
+--disable-terminal      Turn off the embedded terminal in Kanban
+--host <addr>           Bind address (default: 127.0.0.1)
+--allowed-hosts <list>  Extra host names to accept, comma-separated
+--open                  Open the browser on start
 ```
 
+If a port is busy, the hub uses a free port and reports it.
+
+## Included tools
+
+| Tool | Docs | Repo | Submodule | Default port |
+| --- | --- | --- | --- | --- |
+| Kanban | [Docs](https://nikiforovall.blog/claude-code-kanban/) | [claude-code-kanban](https://github.com/NikiforovAll/claude-code-kanban) | `cck/` | 3541 |
+| Marketplace | [Docs](https://nikiforovall.blog/claude-code-marketplace/) | [claude-code-marketplace](https://github.com/NikiforovAll/claude-code-marketplace) | `marketplace/` | 3542 |
+| Cost | [Docs](https://nikiforovall.blog/claude-code-cost/) | [claude-code-cost](https://github.com/NikiforovAll/claude-code-cost) | `cost/` | 3543 |
+| Memory Diagnoser | [Docs](https://nikiforovall.blog/claude-code-memory/) | [claude-code-memory](https://github.com/NikiforovAll/claude-code-memory) | `memory/` | 3544 |
+
 ## License
 
 MIT

package/lib/net-guard.js

@@ -181,6 +181,16 @@ function createNetGuard(config = {}) {
     return next();
   }
 
+  // For a WebSocket upgrade, which originGuard must not judge: the handshake is a
+  // GET, and WebSocket has no CORS, so any page can open one. Browsers always send
+  // Origin on the handshake, so a missing or `null` one is refused, not trusted.
+  // Returns null when allowed, or the reason it was refused.
+  function upgradeVerdict(req) {
+    if (!hostAllowed(parseHostHeader(req.headers.host))) return 'unrecognized Host header';
+    if (originVerdict(req.headers.origin) !== true) return 'cross-origin or missing Origin';
+    return null;
+  }
+
   // Constant for the life of the process, and frameGuard runs ahead of
   // express.static — so this is built once rather than per asset fetch.
   //
@@ -229,12 +239,19 @@ function createNetGuard(config = {}) {
    * @param {any} app express app (or any http request handler)
    * @param {number} port 0 selects a free port
    * @param {(port: number) => void} [onReady]
-   * @param {{maxHeaderSize?: number}} [opts]
+   * `onUpgrade` is attached to both servers; a caller that attached it to the
+   * returned one alone would drop every WebSocket that arrives over the other family.
+   *
+   * @param {{maxHeaderSize?: number, onUpgrade?: (req: any, socket: any, head: Buffer) => void}} [opts]
    */
   function listenLoopback(app, port, onReady, opts = {}) {
     const http = require('http');
     const serverOpts = opts.maxHeaderSize ? { maxHeaderSize: opts.maxHeaderSize } : {};
-    const makeServer = (handler) => http.createServer(serverOpts, handler);
+    const makeServer = (handler) => {
+      const s = http.createServer(serverOpts, handler);
+      if (opts.onUpgrade) s.on('upgrade', opts.onUpgrade);
+      return s;
+    };
     const server = makeServer(app);
     let secondary = null;
 
@@ -261,7 +278,7 @@ function createNetGuard(config = {}) {
     return `WARNING: listening on ${BIND_HOST} - reachable from your network, with no authentication.`;
   }
 
-  return { BIND_HOST, ALLOWED_HOSTS, hostGuard, originGuard, frameGuard, listenLoopback, exposureWarning };
+  return { BIND_HOST, ALLOWED_HOSTS, EXPOSED, hostGuard, originGuard, upgradeVerdict, frameGuard, listenLoopback, exposureWarning };
 }
 
 module.exports = { createNetGuard, parseHostHeader, isLoopbackAddress };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-hub",
-  "version": "0.38.0",
+  "version": "0.39.0-rc.1",
   "description": "Unified hub for Claude Code tools — Marketplace + Kanban in one PWA",
   "main": "server.js",
   "bin": {
@@ -39,10 +39,10 @@
   },
   "homepage": "https://github.com/NikiforovAll/claude-code-hub#readme",
   "dependencies": {
-    "claude-code-cost": "^0.23.1",
-    "claude-code-kanban": "^4.27.0",
-    "claude-code-marketplace": "^0.19.0",
-    "claude-code-memory-explorer": "^0.14.1",
+    "claude-code-cost": "^0.24.0-rc.1",
+    "claude-code-kanban": "^4.28.0-rc.1",
+    "claude-code-marketplace": "^0.20.0-rc.1",
+    "claude-code-memory-explorer": "^0.15.0-rc.1",
     "express": "^4.21.0",
     "open": "^10.1.0"
   },

package/public/app.js

@@ -2,6 +2,7 @@ let apps = {};
 let activeApp = null;
 const iframes = {};
 const loadedApps = new Set();
+const guardedApps = new Set();
 let allowedOrigins = new Set();
 // {theme: 'dark'|'light', colorTheme: '<id>', colorThemes: {<configDir>: '<id>'}} — survives hub
 // reloads so late-loading iframes and fresh sessions get the last chosen theme. Light/dark is
@@ -53,18 +54,30 @@ function themeMessage() {
   return { type: 'hub:theme', theme: themeState.theme ?? osTheme(), colorTheme: activeColorTheme() };
 }
 
-// {<themeId>: {dark, light}} from /api/config, which derives it from scripts/themes.json — the same
-// registry that generates each sub-app's themes.css. Empty until config arrives, and empty if the
-// registry is unreadable; either way the palette keeps the --accent from index.html.
-let themeAccents = {};
+// {<themeId>: {dark, light}}, each a map of CSS variables, from /api/config, which derives it from
+// scripts/themes.json — the same registry that generates each sub-app's themes.css. Empty until
+// config arrives, and empty if the registry is unreadable; then the hub keeps index.html's colors.
+let themePalettes = {};
+// The last applied variables, so the loading screen paints in the theme before /api/config lands.
+const PALETTE_KEY = 'hub-palette';
 
-// Paints the palette — the hub's only themed surface — in the active theme. The hub relays
+// Paints the hub's own surfaces (loading screen, palette) 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() {
   const mode = themeState.theme ?? osTheme();
-  document.documentElement.classList.toggle('light', mode === 'light');
-  const pair = themeAccents[activeColorTheme()];
-  if (pair) document.documentElement.style.setProperty('--accent', pair[mode]);
+  const root = document.documentElement;
+  root.classList.toggle('light', mode === 'light');
+  const key = `${activeColorTheme()}/${mode}`;
+  let vars = themePalettes[activeColorTheme()]?.[mode];
+  try {
+    if (vars) localStorage.setItem(PALETTE_KEY, JSON.stringify({ key, vars }));
+    else {
+      const cached = JSON.parse(localStorage.getItem(PALETTE_KEY));
+      if (cached?.key === key) vars = cached.vars;
+    }
+  } catch {}
+  root.style.cssText = '';
+  for (const [name, value] of Object.entries(vars ?? {})) root.style.setProperty(name, value);
 }
 
 // Claude's on-disk project-directory name. Matches memory/server.js encodeProjectPath. The hub
@@ -103,6 +116,10 @@ function postTo(appId, message) {
   iframes[appId]?.contentWindow?.postMessage(message, originOf(appId));
 }
 
+function appIdOf(source) {
+  return Object.keys(iframes).find((id) => iframes[id].contentWindow === source);
+}
+
 // exceptWindow lets an echo of a sub-app's own message skip that sub-app.
 function broadcast(message, exceptWindow) {
   for (const [id, iframe] of Object.entries(iframes)) {
@@ -131,13 +148,14 @@ async function init() {
   // Twice: light/dark comes from localStorage and shouldn't wait on the fetch, the accent can't be
   // resolved until the registry arrives with it.
   applyHubTheme();
+  showLoading();
   const res = await fetch('/api/config');
   const config = await res.json();
   setApps(config.apps);
   defaultConfigDir = config.defaultConfigDir ?? null;
   activeConfigDir = config.activeConfigDir ?? null;
   applyTitle(config.activeConfigDir);
-  themeAccents = config.themeAccents ?? {};
+  themePalettes = config.themePalettes ?? {};
   applyHubTheme();
   buildIframes();
   switchTab(Object.keys(apps)[0]);
@@ -166,27 +184,91 @@ 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;
-}
+  for (const [id, iframe] of Object.entries(iframes)) iframe.src = appSrc(id);
+}
+
+// The terminal token rides in the fragment so it never reaches a server log or a Referer.
+function appSrc(id, path = '') {
+  const token = apps[id].terminalToken;
+  return apps[id].url + path + (token ? `#t=${token}` : '');
+}
+
+const LOADING_VERBS = {
+  kanban: [
+    'Shuffling cards…',
+    'Herding tasks…',
+    'Waking sessions…',
+    'Sorting the board…',
+    'Pinning sticky notes…',
+    'Moving cards to done…',
+    'Nudging agents…',
+    'Drawing columns…',
+    'Reading the backlog…',
+  ],
+  cost: [
+    'Counting tokens…',
+    'Tallying the bill…',
+    'Stacking bars…',
+    'Crunching numbers…',
+    'Checking the cache hits…',
+    'Adding up the days…',
+    'Balancing the books…',
+    'Plotting the trend…',
+    'Weighing the models…',
+  ],
+  memory: [
+    'Recalling memories…',
+    'Walking the tree…',
+    'Dusting off notes…',
+    'Reading CLAUDE.md…',
+    'Following imports…',
+    'Tracing the context…',
+    'Flipping through pages…',
+    'Connecting the dots…',
+    'Checking what sticks…',
+  ],
+  marketplace: [
+    'Unpacking plugins…',
+    'Polishing skills…',
+    'Dusting off agents…',
+    'Wiring up hooks…',
+    'Fetching manifests…',
+    'Reading SKILL.md files…',
+    'Listing commands…',
+    'Scanning MCP servers…',
+    'Gathering plugins…',
+  ],
+};
 
-function showLoading(text = '') {
-  document.getElementById('loading-text').textContent = text;
+let loadingTimer = null;
+
+function showLoading() {
+  const verbs = LOADING_VERBS[activeApp] ?? Object.values(LOADING_VERBS).flat();
+  const text = document.getElementById('loading-text');
+  let i = Math.floor(Math.random() * verbs.length);
+  text.textContent = verbs[i];
+  clearInterval(loadingTimer);
+  loadingTimer = setInterval(() => {
+    i = (i + 1 + Math.floor(Math.random() * (verbs.length - 1))) % verbs.length;
+    text.textContent = verbs[i];
+  }, 1200);
   document.getElementById('loading-overlay').classList.remove('fade-out');
 }
 
 function hideLoading() {
+  clearInterval(loadingTimer);
   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)) {
+  for (const id of Object.keys(apps)) {
     const iframe = document.createElement('iframe');
     iframe.id = `iframe-${id}`;
-    iframe.src = cfg.url;
+    iframe.src = appSrc(id);
     iframe.className = 'hidden';
-    iframe.allow = 'clipboard-write';
+    iframe.allow = 'clipboard-write; microphone';
     iframe.addEventListener('load', () => onIframeLoad(id));
     container.appendChild(iframe);
     iframes[id] = iframe;
@@ -210,6 +292,7 @@ function switchTab(appId) {
 
 function onIframeLoad(appId) {
   loadedApps.add(appId);
+  guardedApps.delete(appId);
   if (appId === activeApp) hideLoading();
   postTo(appId, themeMessage());
   postProjectTo(appId);
@@ -225,15 +308,38 @@ function onIframeLoad(appId) {
 }
 
 function listenMessages() {
+  window.addEventListener('beforeunload', (e) => {
+    if (guardedApps.size) e.preventDefault();
+  });
   window.addEventListener('message', (e) => {
     if (!allowedOrigins.has(e.origin)) return;
     const data = e.data ?? {};
     if (data.type === 'hub:navigate') {
       if (!apps[data.app]) return;
       switchTab(data.app);
-      if (data.url) iframes[data.app].src = apps[data.app].url + data.url;
+      if (typeof data.url !== 'string' || !data.url) return;
+      // A url such as '@evil.example/' turns the app host into userinfo, and the token rides in the fragment.
+      const src = appSrc(data.app, data.url);
+      if (URL.canParse(src) && new URL(src).origin === originOf(data.app)) iframes[data.app].src = src;
     } else if (data.type === 'hub:keydown') {
       handleForwardedKey(data);
+    } else if (data.type === 'hub:closeGuard') {
+      const appId = appIdOf(e.source);
+      if (!appId) return;
+      if (data.on === true) guardedApps.add(appId);
+      else guardedApps.delete(appId);
+    } else if (data.type === 'hub:terminalToken') {
+      // This hub page may have outlived the restart too, so the cached token is not trusted.
+      const appId = appIdOf(e.source);
+      if (!appId) return;
+      sendJson('GET', '/api/config')
+        .then((cfg) => {
+          const token = cfg.apps?.[appId]?.terminalToken;
+          if (!token) return;
+          apps[appId].terminalToken = token;
+          postTo(appId, { type: 'hub:terminalToken', token });
+        })
+        .catch(() => {});
     } else if (data.type === 'hub:openExternal') {
       // In the installed PWA window a framed sub-app's own target=_blank opens
       // nothing, so the shims hand external links up to the top frame instead.
@@ -372,28 +478,37 @@ function subseq(text, q) {
 }
 
 // Matches the full path so worktrees with opaque basenames stay reachable, but ranks basename
-// hits above parent-path hits. Tier ties fall back to the recency order set in loadProjects.
+// hits above parent-path hits, and within those an exact name, then a prefix, then a word start.
+// Rank 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.
+const PATH_RANK = 4;
+
 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;
-    if (p.path.toLowerCase().includes(q)) return 1;
+  const rankOf = (p) => {
+    const name = p.name.toLowerCase();
+    const at = name.indexOf(q);
+    if (name === q) return 0;
+    if (at === 0) return 1;
+    if (at > 0) return /[^a-z0-9]/.test(name[at - 1]) ? 2 : 3;
+    const path = p.path.toLowerCase();
+    if (path.split(/[/\\]/).includes(q)) return PATH_RANK;
+    if (path.includes(q)) return PATH_RANK + 1;
     return -1;
   };
-  let out = projects.map((p) => ({ p, tier: tierOf(p) })).filter((x) => x.tier >= 0);
+  let out = projects.map((p) => ({ p, rank: rankOf(p) })).filter((x) => x.rank >= 0);
   if (out.length === 0) {
     // Subsequence only as a fallback — it would otherwise swamp real substring matches.
     out = projects
       .map((p) => {
-        const tier = subseq(p.name.toLowerCase(), q) ? 0 : subseq(p.path.toLowerCase(), q) ? 1 : -1;
-        return { p, tier };
+        const rank = subseq(p.name.toLowerCase(), q) ? 0 : subseq(p.path.toLowerCase(), q) ? PATH_RANK : -1;
+        return { p, rank };
       })
-      .filter((x) => x.tier >= 0);
+      .filter((x) => x.rank >= 0);
   }
-  out.sort((a, b) => a.tier - b.tier || b.p.ts - a.p.ts);
-  return out.slice(0, 100);
+  out.sort((a, b) => a.rank - b.rank || b.p.ts - a.p.ts);
+  return out.slice(0, 100).map(({ p, rank }) => ({ p, tier: rank < PATH_RANK ? 0 : 1 }));
 }
 
 // The [start, end) slices of `lower` that q matched, mirroring the tiers in projectRows: one
@@ -673,7 +788,7 @@ 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;
-  showLoading(`Switching to ${target}...`);
+  showLoading();
   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.

package/public/index.html

@@ -25,6 +25,7 @@
       --text: #e8e8ef;
       --text-dim: #8a8fa3;
       --shadow: rgba(0, 0, 0, 0.55);
+      --ghost-mix: 22%;
     }
 
     /* applyHubTheme() owns light/dark and stamps this class, resolving the pushed hub:theme first
@@ -39,6 +40,7 @@
       --text: #18181b;
       --text-dim: #71717a;
       --shadow: rgba(0, 0, 0, 0.18);
+      --ghost-mix: 10%;
     }
 
     * { margin: 0; padding: 0; box-sizing: border-box; }
@@ -78,7 +80,9 @@
       gap: 14px;
       align-items: center;
       justify-content: center;
-      background: var(--bg);
+      background:
+        radial-gradient(circle at 50% 50%, color-mix(in srgb, var(--accent) 14%, transparent), transparent 45%),
+        var(--bg);
       z-index: 10;
       transition: opacity 0.3s ease;
     }
@@ -88,16 +92,85 @@
       pointer-events: none;
     }
 
-    .spinner {
-      width: 28px;
-      height: 28px;
-      border: 3px solid var(--border);
-      border-top-color: var(--accent);
-      border-radius: 50%;
-      animation: spin 0.8s linear infinite;
+    /* Clawd, drawn from the Claude Code banner's block art; cck's boot splash uses the same one. */
+    .clawd {
+      width: 64px;
+      height: 40px;
+      fill: #d97757;
+      overflow: visible;
+      transform-origin: 50% 100%;
+      animation: clawd-jump 0.9s ease-in-out infinite;
+    }
+
+    @keyframes clawd-jump {
+      0%, 100% { transform: translateY(0) scale(1, 1); }
+      15% { transform: translateY(0) scale(1.1, 0.85); }
+      45% { transform: translateY(-14px) scale(0.95, 1.05); }
+      70% { transform: translateY(0) scale(1.08, 0.9); }
+      85% { transform: translateY(0) scale(1, 1); }
     }
 
-    @keyframes spin { to { transform: rotate(360deg); } }
+    @media (prefers-reduced-motion: reduce) {
+      .clawd { animation: none; }
+    }
+
+    /* Faint outlines of the four apps, one per quadrant, so the wait reads as "the pages are
+       coming" rather than a blank screen. */
+    .ghosts {
+      --ghost: color-mix(in srgb, var(--accent) 60%, var(--text-dim));
+      position: absolute;
+      inset: 0;
+      display: grid;
+      grid-template: 1fr 1fr / 1fr 1fr;
+      gap: 16px;
+      padding: 16px;
+      pointer-events: none;
+      -webkit-mask-image: radial-gradient(circle at 50% 50%, transparent 0 80px, #000 240px);
+      mask-image: radial-gradient(circle at 50% 50%, transparent 0 80px, #000 240px);
+    }
+
+    .ghost {
+      display: grid;
+      gap: 12px;
+      padding: 14px;
+      min-height: 0;
+      overflow: hidden;
+      border: 1px solid color-mix(in srgb, var(--ghost) calc(var(--ghost-mix) * 0.8), transparent);
+      border-radius: 10px;
+    }
+
+    .ghost i {
+      display: block;
+      min-height: 12px;
+      border-radius: 6px;
+      background: color-mix(in srgb, var(--ghost) var(--ghost-mix), transparent);
+    }
+
+    .ghost .h { height: 18px; width: 45%; }
+    .ghost .stack { display: flex; flex-direction: column; gap: 10px; min-width: 0; }
+    .ghost .row { display: flex; gap: 16px; }
+    .ghost .row > i { flex: 1; }
+
+    .ghost-kanban { grid-template-columns: 22% repeat(3, 1fr); }
+    .ghost-kanban .side i { height: 24px; }
+    .ghost-kanban .col i:not(.h) { height: 60px; }
+
+    .ghost-cost { grid-template-rows: 56px 1fr auto; }
+    .ghost-cost .row > i { height: 56px; }
+    .ghost-cost .bars { display: flex; align-items: flex-end; gap: 8px; min-height: 0; }
+    .ghost-cost .bars i { flex: 1; }
+    .ghost-cost .stack i:not(.h) { height: 16px; }
+
+    .ghost-memory { grid-template-columns: 28% 1fr; }
+    .ghost-memory .side i { height: 18px; }
+    .ghost-memory .side .in { margin-left: 14px; }
+    .ghost-memory .side .in2 { margin-left: 28px; }
+    .ghost-memory .doc i:not(.h) { height: 12px; }
+
+    .ghost-marketplace { grid-template-rows: 32px 1fr; }
+    .ghost-marketplace .cards { display: grid; grid-template-columns: repeat(3, 1fr); grid-auto-rows: 1fr; gap: 12px; min-height: 0; }
+
+    .loading-overlay > :not(.ghosts) { position: relative; }
 
     .loading-text {
       color: var(--text-dim);
@@ -233,7 +306,48 @@
 <body>
   <div class="iframe-container" id="iframe-container">
     <div class="loading-overlay" id="loading-overlay">
-      <div class="spinner"></div>
+      <div class="ghosts" aria-hidden="true">
+      <div class="ghost ghost-kanban">
+        <div class="stack side"><i class="h"></i><i></i><i></i><i></i><i></i><i></i><i></i><i></i></div>
+        <div class="stack col"><i class="h"></i><i></i><i></i><i></i></div>
+        <div class="stack col"><i class="h"></i><i></i><i></i></div>
+        <div class="stack col"><i class="h"></i><i></i><i></i><i></i><i></i></div>
+      </div>
+      <div class="ghost ghost-cost">
+        <div class="row"><i></i><i></i><i></i><i></i></div>
+        <div class="bars">
+          <i style="height:35%"></i><i style="height:60%"></i><i style="height:45%"></i><i style="height:80%"></i>
+          <i style="height:55%"></i><i style="height:30%"></i><i style="height:70%"></i><i style="height:50%"></i>
+          <i style="height:65%"></i><i style="height:40%"></i><i style="height:75%"></i><i style="height:58%"></i>
+        </div>
+        <div class="stack"><i class="h"></i><i></i><i></i><i></i></div>
+      </div>
+      <div class="ghost ghost-memory">
+        <div class="stack side">
+          <i class="h"></i><i></i><i class="in"></i><i class="in2"></i><i class="in2"></i><i class="in"></i>
+          <i></i><i class="in"></i><i class="in2"></i><i class="in"></i><i></i>
+        </div>
+        <div class="stack doc">
+          <i class="h"></i><i></i><i></i><i style="width:70%"></i><i></i><i style="width:85%"></i><i style="width:40%"></i>
+        </div>
+      </div>
+      <div class="ghost ghost-marketplace">
+        <i></i>
+        <div class="cards"><i></i><i></i><i></i><i></i><i></i><i></i><i></i><i></i><i></i></div>
+      </div>
+      </div>
+      <svg class="clawd" viewBox="1 0 16 10" shape-rendering="crispEdges" aria-hidden="true">
+        <rect x="3" y="0" width="12" height="2"/>
+        <rect x="3" y="2" width="2" height="2"/>
+        <rect x="6" y="2" width="6" height="2"/>
+        <rect x="13" y="2" width="2" height="2"/>
+        <rect x="1" y="4" width="16" height="2"/>
+        <rect x="3" y="6" width="12" height="2"/>
+        <rect x="4" y="8" width="1" height="2"/>
+        <rect x="6" y="8" width="1" height="2"/>
+        <rect x="11" y="8" width="1" height="2"/>
+        <rect x="13" y="8" width="1" height="2"/>
+      </svg>
       <div class="loading-text" id="loading-text"></div>
     </div>
   </div>

package/public/locked.html

@@ -0,0 +1,169 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <link rel="manifest" href="/manifest.json">
+  <link rel="icon" type="image/svg+xml" href="/icons/icon-192.svg">
+  <link rel="icon" type="image/png" sizes="192x192" href="/icons/icon-192.png">
+  <title>Claude Code Hub</title>
+  <style>
+    :root {
+      --bg: #1a1a2e;
+      --border: #0f3460;
+      --accent: #e86f33;
+      --surface: #16213e;
+      --surface-hover: #1f2a4a;
+      --text: #e8e8ef;
+      --text-dim: #8a8fa3;
+      --shadow: rgba(0, 0, 0, 0.55);
+    }
+
+    :root.light {
+      --bg: #f4f4f5;
+      --border: #e4e4e7;
+      --surface: #ffffff;
+      --surface-hover: #f1f1f4;
+      --text: #18181b;
+      --text-dim: #71717a;
+      --shadow: rgba(0, 0, 0, 0.18);
+    }
+
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+
+    body {
+      min-height: 100vh;
+      display: grid;
+      place-items: center;
+      padding: 16px;
+      background:
+        radial-gradient(circle at 50% 42%, color-mix(in srgb, var(--accent) 14%, transparent), transparent 45%),
+        var(--bg);
+      color: var(--text);
+      font: 14px/1.5 ui-monospace, SFMono-Regular, Menlo, monospace;
+    }
+
+    main {
+      width: min(440px, 100%);
+      display: grid;
+      justify-items: center;
+      gap: 20px;
+    }
+
+    .clawd {
+      width: 64px;
+      height: 40px;
+      fill: #d97757;
+    }
+
+    .card {
+      width: 100%;
+      display: grid;
+      gap: 14px;
+      padding: 22px;
+      background: var(--surface);
+      border: 1px solid var(--border);
+      border-radius: 12px;
+      box-shadow: 0 16px 48px var(--shadow);
+    }
+
+    h1 { font-size: 16px; font-weight: 600; }
+
+    p { color: var(--text-dim); font-size: 13px; }
+
+    code {
+      padding: 1px 5px;
+      border-radius: 4px;
+      background: var(--surface-hover);
+      color: var(--text);
+      font: inherit;
+    }
+
+    form { display: flex; gap: 8px; }
+
+    input {
+      flex: 1;
+      min-width: 0;
+      padding: 9px 12px;
+      border: 1px solid var(--border);
+      border-radius: 8px;
+      background: var(--bg);
+      color: var(--text);
+      font: inherit;
+    }
+
+    button {
+      padding: 9px 16px;
+      border: none;
+      border-radius: 8px;
+      background: var(--accent);
+      color: #fff;
+      font: inherit;
+      font-weight: 600;
+      cursor: pointer;
+    }
+
+    button:hover { filter: brightness(1.08); }
+
+    button:focus-visible, input:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
+
+    .error { color: #e5484d; }
+
+    .error:empty { display: none; }
+  </style>
+  <script>
+    (() => {
+      let mode;
+      let cached;
+      try {
+        mode = JSON.parse(localStorage.getItem('hub-theme'))?.theme;
+        cached = JSON.parse(localStorage.getItem('hub-palette'));
+      } catch {}
+      mode ??= matchMedia('(prefers-color-scheme: light)').matches ? 'light' : 'dark';
+      const root = document.documentElement;
+      root.classList.toggle('light', mode === 'light');
+      if (cached?.key?.endsWith(`/${mode}`)) {
+        for (const [name, value] of Object.entries(cached.vars ?? {})) root.style.setProperty(name, value);
+      }
+    })();
+  </script>
+</head>
+<body>
+  <main>
+    <svg class="clawd" viewBox="1 0 16 10" shape-rendering="crispEdges" aria-hidden="true">
+      <rect x="3" y="0" width="12" height="2"/>
+      <rect x="3" y="2" width="2" height="2"/>
+      <rect x="6" y="2" width="6" height="2"/>
+      <rect x="13" y="2" width="2" height="2"/>
+      <rect x="1" y="4" width="16" height="2"/>
+      <rect x="3" y="6" width="12" height="2"/>
+      <rect x="4" y="8" width="1" height="2"/>
+      <rect x="6" y="8" width="1" height="2"/>
+      <rect x="11" y="8" width="1" height="2"/>
+      <rect x="13" y="8" width="1" height="2"/>
+    </svg>
+    <div class="card">
+      <h1>Unlock Claude Code Hub</h1>
+      <p>Open the link the hub prints when it starts, or paste the token from <code>~/.claude-hub/token</code>. This browser remembers it.</p>
+      <form id="unlock">
+        <input id="token" type="password" autocomplete="off" spellcheck="false" placeholder="Access token" aria-label="Access token" required autofocus>
+        <button type="submit">Unlock</button>
+      </form>
+      <p class="error" id="error" role="alert"></p>
+    </div>
+  </main>
+  <script>
+    const params = new URLSearchParams(location.search);
+    if (params.has('token')) {
+      document.getElementById('error').textContent = 'That token does not match. Check it and try again.';
+      params.delete('token');
+      history.replaceState(null, '', location.pathname + (params.size ? `?${params}` : ''));
+    }
+    document.getElementById('unlock').addEventListener('submit', (e) => {
+      e.preventDefault();
+      params.set('token', document.getElementById('token').value.trim());
+      location.replace(`${location.pathname}?${params}`);
+    });
+  </script>
+</body>
+</html>

package/public/sw.js

@@ -1,4 +1,4 @@
-const CACHE_NAME = 'hub-shell-v1';
+const CACHE_NAME = 'hub-shell-v2';
 const SHELL_ASSETS = ['/', '/index.html', '/app.js', '/manifest.json'];
 
 self.addEventListener('install', (e) => {
@@ -23,6 +23,16 @@ self.addEventListener('fetch', (e) => {
     return;
   }
   e.respondWith(
-    fetch(e.request).catch(() => caches.match(e.request))
+    fetch(e.request)
+      .then((res) => {
+        // Refresh the copy, or a load while the hub restarts serves the shell from install time.
+        if (res.ok && e.request.method === 'GET' && SHELL_ASSETS.includes(new URL(e.request.url).pathname)) {
+          const copy = res.clone();
+          e.waitUntil(caches.open(CACHE_NAME).then((cache) => cache.put(e.request, copy)));
+        }
+        return res;
+      })
+      // respondWith(undefined) throws, so a miss while the server is down must still be a Response.
+      .catch(() => caches.match(e.request).then((cached) => cached || Response.error()))
   );
 });

package/server.js

@@ -1,9 +1,11 @@
 #!/usr/bin/env node
 
 const { spawn } = require('child_process');
+const crypto = require('crypto');
 const express = require('express');
 const fs = require('fs');
 const http = require('http');
+const tcp = require('net');
 const os = require('os');
 const path = require('path');
 const { createNetGuard } = require('./lib/net-guard');
@@ -42,7 +44,8 @@ function activePool() {
 // 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');
+const HUB_DIR = path.join(os.homedir(), '.claude-hub');
+const HUB_CONFIG_FILE = path.join(HUB_DIR, 'config.json');
 
 // The dir the hub would use with no saved config. Set by loadHubConfig; the client uses it to keep
 // the default dir out of the window title.
@@ -82,6 +85,8 @@ function loadHubConfig() {
   const savedActive = typeof saved.activeConfigDir === 'string' ? canonical(saved.activeConfigDir) : null;
   const active = dirs.includes(savedActive) ? savedActive : fallback;
   const config = { configDirs: dirs, activeConfigDir: active };
+  // Hand-edited only; kept verbatim so a rewrite of the file does not drop it.
+  if (saved.terminal && typeof saved.terminal === 'object') config.terminal = saved.terminal;
   // Configs saved before canonicalization can hold one dir under two spellings; persist the merge.
   if (serializeConfig(config) !== raw) writeHubConfig(config);
   return config;
@@ -107,18 +112,83 @@ const hubConfig = loadHubConfig();
 // while every iframe 403'd on its own Host check.
 const net = createNetGuard({ appName: 'Claude Code Hub' });
 
+// cck's embedded terminal, on by default under the hub (standalone cck keeps it opt-in).
+// `"terminal": {"enabled": false}` or --disable-terminal turns it off. One token per hub launch,
+// shared by every pool: the hub puts it in the kanban iframe's URL fragment and cck checks it on
+// the WebSocket. cck applies the rest of its policy (exposure refusal, Origin, session cap) itself.
+const TERMINAL = {
+  ...(hubConfig.terminal || {}),
+  enabled: !process.argv.includes('--disable-terminal') && hubConfig.terminal?.enabled !== false,
+};
+const TERMINAL_TOKEN = TERMINAL.enabled ? crypto.randomBytes(32).toString('hex') : null;
+
+// Loopback is not a user boundary: any local account can reach the hub port, and /api/config carries
+// the terminal token. Persisted, unlike the terminal token, so an installed PWA's cookie outlives a
+// hub restart.
+const HUB_TOKEN_FILE = path.join(HUB_DIR, 'token');
+const TOKEN_COOKIE = 'hub_token';
+const TOKEN_COOKIE_RE = /(?:^|;\s*)hub_token=([^;]*)/;
+const TOKEN_COOKIE_MAX_AGE_MS = 400 * 24 * 60 * 60 * 1000;
+const LOCKED_PAGE = path.join(__dirname, 'public', 'locked.html');
+
+function loadHubToken() {
+  try {
+    const saved = fs.readFileSync(HUB_TOKEN_FILE, 'utf8').trim();
+    if (/^[0-9a-f]{64}$/.test(saved)) return saved;
+  } catch {}
+  const token = crypto.randomBytes(32).toString('hex');
+  fs.mkdirSync(HUB_DIR, { recursive: true, mode: 0o700 });
+  fs.writeFileSync(HUB_TOKEN_FILE, `${token}\n`, { mode: 0o600 });
+  return token;
+}
+
+const HUB_TOKEN = loadHubToken();
+const HUB_TOKEN_BUF = Buffer.from(HUB_TOKEN);
+
+function tokenMatches(candidate) {
+  if (typeof candidate !== 'string' || candidate.length !== HUB_TOKEN.length) return false;
+  return crypto.timingSafeEqual(Buffer.from(candidate), HUB_TOKEN_BUF);
+}
+
+// Scripts, styles, icons and the manifest stay public: they hold no secrets, and Chrome fetches the
+// manifest without cookies, so gating it would break PWA install.
+function tokenGuard(req, res, next) {
+  const isApi = req.path.startsWith('/api/');
+  if (!isApi && req.path !== '/' && req.path !== '/index.html') return next();
+  if (tokenMatches(req.query.token)) {
+    res.cookie(TOKEN_COOKIE, HUB_TOKEN, { httpOnly: true, sameSite: 'strict', maxAge: TOKEN_COOKIE_MAX_AGE_MS });
+    if (isApi) return next();
+    const url = new URL(req.originalUrl, 'http://hub');
+    url.searchParams.delete('token');
+    return res.redirect(302, url.pathname + url.search);
+  }
+  if (tokenMatches(TOKEN_COOKIE_RE.exec(req.headers.cookie || '')?.[1])) return next();
+  res.setHeader('Cache-Control', 'no-store');
+  if (isApi) return res.status(401).json({ error: 'hub token required' });
+  res.status(401).sendFile(LOCKED_PAGE, { cacheControl: false });
+}
+
+function childEnv(pool, name) {
+  const env = {
+    ...process.env,
+    PORT: '0',
+    CLAUDE_CONFIG_DIR: pool.dir,
+    CLAUDE_HUB: '1',
+    HUB_URL: `http://localhost:${HUB_PORT}`,
+    HOST: net.BIND_HOST,
+    ALLOWED_HOSTS: net.ALLOWED_HOSTS,
+  };
+  if (name === 'kanban' && TERMINAL.enabled) {
+    env.CCK_TERMINAL = JSON.stringify(TERMINAL);
+    env.CCK_TERMINAL_TOKEN = TERMINAL_TOKEN;
+  }
+  return env;
+}
+
 function spawnApp(pool, name, cmd, args) {
   const child = spawn(cmd, args, {
     cwd: __dirname,
-    env: {
-      ...process.env,
-      PORT: '0',
-      CLAUDE_CONFIG_DIR: pool.dir,
-      CLAUDE_HUB: '1',
-      HUB_URL: `http://localhost:${HUB_PORT}`,
-      HOST: net.BIND_HOST,
-      ALLOWED_HOSTS: net.ALLOWED_HOSTS,
-    },
+    env: childEnv(pool, name),
     stdio: ['ignore', 'pipe', 'pipe'],
   });
 
@@ -204,11 +274,9 @@ async function ensurePool(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);
-  }
+  if (pools.size >= POOL_SIZE) await evictPools(dir);
+  pool = pools.get(dir);
+  if (pool) return pool.ready;
   pool = { dir, children: new Map(), ports: {}, restarts: {}, retired: false };
   pools.set(dir, pool);
   spawnChildren(pool);
@@ -217,6 +285,37 @@ async function ensurePool(dir) {
   return pool.ready;
 }
 
+async function terminalCount(pool) {
+  const port = pool.ports.kanban;
+  if (!port) return 0;
+  try {
+    const r = await fetch(`http://127.0.0.1:${port}/api/terminals`, { signal: AbortSignal.timeout(1500) });
+    return r.ok ? (await r.json()).sessions?.length || 0 : 0;
+  } catch {
+    return 0;
+  }
+}
+
+// A pool whose cck holds live terminals is pinned: killing it would kill running claude sessions.
+// When every candidate is pinned the pool size is exceeded rather than losing work.
+async function evictPools(keepDir) {
+  let pinned = new Set();
+  if (TERMINAL.enabled) {
+    const candidates = [...pools.values()].filter((p) => p.dir !== 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) {
+    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`);
+      return;
+    }
+    console.log(`Evicting children for ${victim}`);
+    dropPool(victim);
+  }
+}
+
 function dropPool(dir) {
   const pool = pools.get(dir);
   if (!pool) return;
@@ -454,12 +553,44 @@ function proxyHandler(name) {
   };
 }
 
-function listenWithFallback(handler, port, onReady, label) {
-  const server = net.listenLoopback(handler, port, onReady, { maxHeaderSize: HDR_BYTES });
+// WebSocket upgrades (cck's terminal) are tunnelled as raw bytes for every app. Host and Origin get
+// the same treatment as proxyHandler; the child runs its own upgrade checks, and a child with no
+// upgrade listener closes the socket.
+function proxyUpgrade(name) {
+  return async (req, socket, head) => {
+    socket.on('error', () => socket.destroy());
+    const childPort = await waitForPort(name, Date.now() + API_PORT_WAIT_MS);
+    if (!childPort || socket.destroyed) {
+      socket.destroy();
+      return;
+    }
+    const lines = [`${req.method} ${req.url} HTTP/${req.httpVersion}`];
+    for (let i = 0; i < req.rawHeaders.length; i += 2) {
+      let value = req.rawHeaders[i + 1];
+      if (req.rawHeaders[i].toLowerCase() === 'origin') value = rewriteOrigin(value, publicPorts[name], childPort);
+      lines.push(`${req.rawHeaders[i]}: ${value}`);
+    }
+    const upstream = tcp.connect(childPort, '127.0.0.1', () => {
+      clearTimeout(connectTimer);
+      upstream.write(`${lines.join('\r\n')}\r\n\r\n`);
+      if (head?.length) upstream.write(head);
+      upstream.pipe(socket);
+      socket.pipe(upstream);
+    });
+    const connectTimer = setTimeout(() => upstream.destroy(), CONNECT_TIMEOUT_MS);
+    upstream.on('error', () => socket.destroy());
+    socket.on('close', () => upstream.destroy());
+    upstream.on('close', () => socket.destroy());
+  };
+}
+
+function listenWithFallback(handler, port, onReady, label, onUpgrade) {
+  const opts = { maxHeaderSize: HDR_BYTES, onUpgrade };
+  const server = net.listenLoopback(handler, port, onReady, opts);
   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 });
+    net.listenLoopback(handler, 0, onReady, opts);
   });
   return server;
 }
@@ -472,28 +603,40 @@ for (const [name, port] of Object.entries(DEFAULT_PORTS)) {
       publicPorts[name] = actual;
     },
     `[${name}] `,
+    proxyUpgrade(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.
 app.use(net.hostGuard);
 app.use(net.frameGuard);
 app.use(net.originGuard);
+app.use(tokenGuard);
+app.use(express.json());
 
-// The accent hex per color theme, read from the same registry generate-themes.mjs compiles into each
-// sub-app's themes.css. Served rather than hand-copied into public/app.js so there is one source of
-// truth; the palette is the hub's only themed surface, so only ember (the accent role) is needed.
+// The hub's CSS variables per color theme and mode, read from the same registry generate-themes.mjs
+// compiles into each sub-app's themes.css. Served rather than hand-copied into public/app.js so there
+// is one source of truth. --bg is the sub-apps' --bg-deep, so the loading screen hands off to an
+// iframe without a flash of another color.
 // Read once — themes.json only changes when the generator is re-run, which restarts the hub anyway.
-const themeAccents = (() => {
+const hubVars = (p) => ({
+  '--accent': p.ember,
+  '--bg': p.field,
+  '--surface': p.surface,
+  '--surface-hover': p.hover,
+  '--border': p.border,
+  '--text': p.ink1,
+  '--text-dim': p.inkMuted,
+});
+const themePalettes = (() => {
   try {
     const themes = JSON.parse(fs.readFileSync(path.join(__dirname, 'scripts/themes.json'), 'utf8'));
-    return Object.fromEntries(themes.map((t) => [t.id, { dark: t.dark.ember, light: t.light.ember }]));
+    return Object.fromEntries(themes.map((t) => [t.id, { dark: hubVars(t.dark), light: hubVars(t.light) }]));
   } catch {
     // Palette falls back to the --accent in index.html; not worth failing startup over.
     return {};
@@ -501,8 +644,10 @@ const themeAccents = (() => {
 })();
 
 function appsConfig() {
+  const kanban = { name: 'Kanban', url: `http://localhost:${publicPorts.kanban}`, icon: 'columns' };
+  if (TERMINAL_TOKEN) kanban.terminalToken = TERMINAL_TOKEN;
   return {
-    kanban: { name: 'Kanban', url: `http://localhost:${publicPorts.kanban}`, icon: 'columns' },
+    kanban,
     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' },
@@ -510,7 +655,7 @@ function appsConfig() {
 }
 
 app.get('/api/config', (_req, res) => {
-  res.json({ themeAccents, apps: appsConfig(), activeConfigDir: hubConfig.activeConfigDir, defaultConfigDir });
+  res.json({ themePalettes, apps: appsConfig(), activeConfigDir: hubConfig.activeConfigDir, defaultConfigDir });
 });
 
 app.get('/api/config-dirs', (_req, res) => {
@@ -615,14 +760,18 @@ app.use(express.static(path.join(__dirname, 'public')));
 const onReady = (actual) => {
   printBanner(actual);
   if (process.argv.includes('--open')) {
-    import('open').then((m) => m.default(`http://localhost:${actual}`));
+    import('open').then((m) => m.default(accessUrl(actual)));
   }
 };
 
 listenWithFallback(app, HUB_PORT, onReady, '');
 
+function accessUrl(port) {
+  return `http://localhost:${port}/?token=${HUB_TOKEN}`;
+}
+
 function printBanner(port) {
-  console.log(`Claude Code Hub running at http://localhost:${port}`);
+  console.log(`Claude Code Hub running at ${accessUrl(port)}`);
   const warning = net.exposureWarning();
   if (warning) console.log(warning);
   console.log('Type "q" or "exit" to stop the server');