claude-code-hub 1.5.1 → 1.7.0

package/README.md

@@ -157,6 +157,8 @@ The hub has no visible UI of its own. Use these shortcuts:
 
 <kbd>Alt</kbd>+<kbd>1</kbd> to <kbd>Alt</kbd>+<kbd>4</kbd> follow the tab order, so they change when you [choose the tools](#choose-the-tools).
 
+On macOS, every hub key is <kbd>Control</kbd>+<kbd>Option</kbd> with a key, the tool numbers too: <kbd>⌃⌥1</kbd> to <kbd>⌃⌥4</kbd>. <kbd>Option</kbd> with a digit types a character there, so the hub leaves it to the tools.
+
 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:
@@ -180,16 +182,17 @@ The shortcuts also work when focus is inside a tool. Kanban keeps <kbd>Ctrl</kbd
 --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
---tray                  Windows: run the hub from a tray icon
---autostart             Windows: same as --tray, and start the tray at logon
---no-autostart          Windows: stop starting the tray at logon
---tray-status           Windows: show whether autostart is on and the tray and hub are running
---app-id <id>           Windows, with --tray or --autostart: the installed app that Open Hub starts
+--detached              Keep running when stdin closes (the macOS tray uses it)
+--tray                  Windows, macOS: run the hub from a tray icon
+--autostart             Windows, macOS: same as --tray, and start the tray at logon
+--no-autostart          Windows, macOS: stop starting the tray at logon
+--tray-status           Windows, macOS: show whether autostart is on and the tray and hub are running
+--app-id <id>           Windows, macOS, with --tray or --autostart: the installed app that Open Hub starts
 ```
 
 If a port is busy, the hub uses a free port and reports it.
 
-## Tray icon (Windows)
+## Tray icon (Windows, macOS)
 
 ```
 claude-code-hub --autostart
@@ -197,6 +200,8 @@ claude-code-hub --autostart
 
 The hub runs in the background with an icon in the notification area. Click the icon to open the hub. Right-click it to stop, start or restart the hub, open its log, turn **Start with Windows** on or off, or quit. The dot on the icon shows the state: green is running, amber is starting, red is stopped. If the hub stops unexpectedly, the tray shows a notice and turns red; start the hub again from the menu.
 
+On macOS (experimental), the icon is in the menu bar.
+
 To turn off autostart, untick **Start with Windows** or run `claude-code-hub --no-autostart`. To check the state, run `claude-code-hub --tray-status`. See [Run the hub from the tray](https://nikiforovall.blog/claude-code-hub/guides/tray/).
 
 ## Included tools

package/lib/apps.js

@@ -3,6 +3,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const { isContained } = require('./contain');
+const { COMBO_RE } = require('./keymap');
 
 // Built-in apps in their default tab order. The rest of each app comes from its manifest.
 const APPS = [
@@ -64,7 +65,18 @@ function manifestError(m, id, root) {
   if (typeof m.run?.entry !== 'string') return 'run.entry is missing';
   const entry = path.resolve(root, m.run.entry);
   if (entry === path.resolve(root) || !isContained(entry, root)) return 'run.entry is outside the app directory';
-  return providesError(m.provides) ?? publishesError(m.publishes);
+  return providesError(m.provides) ?? publishesError(m.publishes) ?? keysError(m.keys);
+}
+
+function keysError(keys) {
+  if (keys === undefined) return null;
+  if (typeof keys !== 'object' || keys === null || Array.isArray(keys)) return 'keys is not an object';
+  if (keys.keeps === undefined) return null;
+  if (!Array.isArray(keys.keeps)) return 'keys.keeps is not an array';
+  for (const c of keys.keeps) {
+    if (typeof c !== 'string' || !COMBO_RE.test(c)) return `keys.keeps combo ${JSON.stringify(c)} is not a combo name`;
+  }
+  return null;
 }
 
 const TOPIC_RE = /^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)+$/;
@@ -144,6 +156,7 @@ function loadApp(app, { flagPort, hubRoot = HUB_ROOT, resolve = require.resolve,
     actions: manifest.actions ?? {},
     provides: manifest.provides ?? {},
     publishes: manifest.publishes ?? [],
+    keeps: manifest.keys?.keeps ?? [],
   };
 }
 

package/lib/keymap.js

@@ -0,0 +1,78 @@
+'use strict';
+
+// The actions a user can rebind in config.json `keys`. Their defaults are in hubActions() in
+// public/app.js; test/keys.test.js checks that the two lists match.
+const HUB_ACTIONS = [
+  'hub.projectPicker',
+  'hub.configDirPicker',
+  'hub.appLauncher',
+  'hub.prevApp',
+  'hub.nextApp',
+  'hub.appByNumber',
+];
+// {n} stands for the tab number, 1 to 9.
+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]+)$/;
+
+// "Ctrl+Alt+O" → "ctrl+alt+o", the form comboOf() gives. Null when the text cannot name a combo.
+function normalizeCombo(text) {
+  if (typeof text !== 'string') return null;
+  const parts = text.split('+').map((p) => p.trim());
+  let key = parts.pop();
+  const mods = parts.map((p) => p.toLowerCase());
+  if (mods.some((m) => !MODS.includes(m)) || new Set(mods).size !== mods.length) return null;
+  if (key.length === 1) key = key.toLowerCase();
+  const combo = [...MODS.filter((m) => mods.includes(m)), key].join('+');
+  return COMBO_RE.test(combo.replace(/\+\{n\}$/, '+1')) ? combo : null;
+}
+
+// The `keys` of config.json, checked, as {actionId: combo | null}; null unbinds the action. An
+// entry that is not valid, takes a combo an app keeps or repeats an earlier entry's combo is left
+// out with a line that says why, so that action keeps its default.
+function userKeys(saved, apps) {
+  const keys = {};
+  const lines = [];
+  if (saved === undefined) return { keys, lines };
+  if (!saved || typeof saved !== 'object' || Array.isArray(saved)) {
+    lines.push('keys is not an object, ignored');
+    return { keys, lines };
+  }
+  const kept = new Map(apps.flatMap((a) => a.keeps.map((c) => [c, a.id])));
+  const owner = new Map();
+  for (const [id, value] of Object.entries(saved)) {
+    const drop = (why) => lines.push(`keys "${id}": ${why}. It keeps its default`);
+    if (!HUB_ACTIONS.includes(id)) {
+      lines.push(`keys "${id}" is not a hub action, ignored`);
+      continue;
+    }
+    if (value === null) {
+      keys[id] = null;
+      continue;
+    }
+    const combo = normalizeCombo(value);
+    const pattern = PATTERN_ACTIONS.has(id);
+    if (!combo || pattern !== combo.endsWith('+{n}')) {
+      drop(`${JSON.stringify(value)} is not a combo${pattern ? ' that ends in +{n}' : ''}`);
+      continue;
+    }
+    const combos = pattern ? Array.from({ length: 9 }, (_, i) => combo.replace('{n}', i + 1)) : [combo];
+    const keptCombo = combos.find((c) => kept.has(c));
+    if (keptCombo) {
+      drop(`${keptCombo} is kept by ${kept.get(keptCombo)}`);
+      continue;
+    }
+    const taken = combos.find((c) => owner.has(c));
+    if (taken) {
+      drop(`${taken} is already set for "${owner.get(taken)}"`);
+      continue;
+    }
+    for (const c of combos) owner.set(c, id);
+    keys[id] = combo;
+  }
+  return { keys, lines };
+}
+
+module.exports = { HUB_ACTIONS, COMBO_RE, normalizeCombo, userKeys };

package/lib/tray.js

@@ -3,17 +3,55 @@
 const { execFileSync, spawn } = require('node:child_process');
 const crypto = require('node:crypto');
 const fs = require('node:fs');
+const os = require('node:os');
 const path = require('node:path');
 const { version } = require('../package.json');
 const { liveHub } = require('./hub-record');
 
 const TRAY_SRC = path.join(__dirname, '..', 'tray');
 const RUN_KEY = 'HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Run';
+const LAUNCH_AGENTS = path.join(os.homedir(), 'Library', 'LaunchAgents');
+
+function dirHash(hubDir) {
+  return crypto.createHash('sha1').update(path.resolve(hubDir).toLowerCase()).digest('hex').slice(0, 8);
+}
 
 // One Run value and one tray per hub dir, so a test hub never replaces the real autostart.
 function runValue(hubDir) {
-  const hash = crypto.createHash('sha1').update(path.resolve(hubDir).toLowerCase()).digest('hex').slice(0, 8);
-  return `ClaudeCodeHub-${hash}`;
+  return `ClaudeCodeHub-${dirHash(hubDir)}`;
+}
+
+function launchAgentLabel(hubDir) {
+  return `com.claude-code-hub.tray.${dirHash(hubDir)}`;
+}
+
+const xml = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+
+// AbandonProcessGroup: launchd kills what is left in a job's process group when the job exits,
+// and the hub that the tray started is in it.
+function launchAgentPlist({ label, script }) {
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${xml(label)}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>/usr/bin/osascript</string>
+    <string>-l</string>
+    <string>JavaScript</string>
+    <string>${xml(script)}</string>
+  </array>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>ProcessType</key>
+  <string>Interactive</string>
+  <key>AbandonProcessGroup</key>
+  <true/>
+</dict>
+</plist>
+`;
 }
 
 // An installed app is bound to the origin it was installed from, and its shortcut does not record
@@ -22,8 +60,75 @@ function appConfig({ appId, port, defaultPort }) {
   return appId ? { id: appId, port } : { name: 'Claude Code Hub', port: defaultPort };
 }
 
+// A pid file outlives its process, and pids are reused, so the process must still be the tray.
+// tray/mac/hub-tray.js makes the same check before it starts.
+function windows(hubDir) {
+  const value = runValue(hubDir);
+  const launcher = path.join(hubDir, 'tray', 'launch.vbs');
+  return {
+    area: 'notification area',
+    prepare: () => ({ runValue: value }),
+    trayAlive(pid) {
+      const out = execFileSync('tasklist', ['/fi', `PID eq ${pid}`, '/fo', 'csv', '/nh'], { encoding: 'utf8' });
+      return out.toLowerCase().startsWith('"powershell.exe"');
+    },
+    autostartName() {
+      try {
+        execFileSync('reg', ['query', RUN_KEY, '/v', value], { stdio: 'ignore' });
+        return value;
+      } catch {
+        return null;
+      }
+    },
+    addAutostart() {
+      execFileSync('reg', ['add', RUN_KEY, '/v', value, '/t', 'REG_SZ', '/d', `wscript.exe "${launcher}"`, '/f'], { stdio: 'ignore' });
+    },
+    removeAutostart() {
+      try {
+        execFileSync('reg', ['delete', RUN_KEY, '/v', value, '/f'], { stdio: 'ignore' });
+        return true;
+      } catch {
+        return false;
+      }
+    },
+    start: () => spawn('wscript.exe', [launcher], { detached: true, stdio: 'ignore' }).unref(),
+  };
+}
+
+function macos(hubDir, launchAgentsDir) {
+  const label = launchAgentLabel(hubDir);
+  const plist = path.join(launchAgentsDir, `${label}.plist`);
+  const launcher = path.join(hubDir, 'tray', 'mac', 'hub-tray.js');
+  const trayPlist = path.join(hubDir, 'tray', 'mac', 'autostart.plist');
+  return {
+    area: 'menu bar',
+    prepare() {
+      fs.writeFileSync(trayPlist, launchAgentPlist({ label, script: launcher }));
+      return { launchAgent: plist, path: process.env.PATH };
+    },
+    trayAlive(pid) {
+      try {
+        return execFileSync('ps', ['-p', String(pid), '-o', 'command='], { encoding: 'utf8' }).includes('hub-tray.js');
+      } catch {
+        return false;
+      }
+    },
+    autostartName: () => (fs.existsSync(plist) ? label : null),
+    addAutostart() {
+      fs.mkdirSync(launchAgentsDir, { recursive: true });
+      fs.copyFileSync(trayPlist, plist);
+    },
+    removeAutostart() {
+      if (!fs.existsSync(plist)) return false;
+      fs.rmSync(plist);
+      return true;
+    },
+    start: () => spawn('/usr/bin/osascript', ['-l', 'JavaScript', launcher], { detached: true, stdio: 'ignore' }).unref(),
+  };
+}
+
 // The Run key and the tray start from this copy, never from the package: an npx cache path can vanish.
-function copyTray({ hubDir, port, appId, defaultPort, value }) {
+function copyTray(plat, { hubDir, port, appId, defaultPort }) {
   const dest = path.join(hubDir, 'tray');
   fs.rmSync(dest, { recursive: true, force: true });
   fs.cpSync(TRAY_SRC, dest, { recursive: true });
@@ -33,25 +138,14 @@ function copyTray({ hubDir, port, appId, defaultPort, value }) {
     version,
     serverJs: path.join(__dirname, '..', 'server.js'),
     node: process.execPath,
-    runValue: value,
+    ...plat.prepare(),
   };
   fs.writeFileSync(path.join(dest, 'config.json'), `${JSON.stringify(config, null, 2)}\n`);
-  return path.join(dest, 'launch.vbs');
+  return dest;
 }
 
-// A pid file outlives its process, and Windows reuses pids, so the image name must match too.
-function pidAlive(pid, image) {
-  if (!Number.isInteger(pid)) return false;
-  const out = execFileSync('tasklist', ['/fi', `PID eq ${pid}`, '/fo', 'csv', '/nh'], { encoding: 'utf8' });
-  return out.toLowerCase().startsWith(`"${image}"`);
-}
-
-async function printStatus({ hubDir, configDir, value }) {
-  let autostart = 'off';
-  try {
-    execFileSync('reg', ['query', RUN_KEY, '/v', value], { stdio: 'ignore' });
-    autostart = `on (${value})`;
-  } catch {}
+async function printStatus(plat, { hubDir, configDir }) {
+  const autostart = plat.autostartName();
   let trayPid = null;
   try {
     trayPid = Number.parseInt(fs.readFileSync(path.join(hubDir, 'tray.pid'), 'utf8'), 10);
@@ -62,39 +156,33 @@ async function printStatus({ hubDir, configDir, value }) {
   } catch {}
   console.log(`  Hub dir: ${hubDir}`);
   console.log(`  Config dir: ${configDir}`);
-  console.log(`  Autostart: ${autostart}`);
-  console.log(`  Tray: ${pidAlive(trayPid, 'powershell.exe') ? `running (pid ${trayPid})` : 'not running'}`);
+  console.log(`  Autostart: ${autostart ? `on (${autostart})` : 'off'}`);
+  console.log(`  Tray: ${Number.isInteger(trayPid) && plat.trayAlive(trayPid) ? `running (pid ${trayPid})` : 'not running'}`);
   console.log(`  Hub: ${hub ? `running on port ${hub.port} (pid ${hub.pid})` : 'stopped'}`);
 }
 
-async function runTrayCommand({ flag, hubDir, port, defaultPort, appId, configDir, platform = process.platform }) {
-  if (platform !== 'win32') {
-    console.error(`  ${flag} works only on Windows.`);
+async function runTrayCommand({ flag, platform = process.platform, launchAgentsDir = LAUNCH_AGENTS, ...opts }) {
+  if (platform !== 'win32' && platform !== 'darwin') {
+    console.error(`  ${flag} works only on Windows and macOS.`);
     return false;
   }
-  const value = runValue(hubDir);
+  const plat = platform === 'darwin' ? macos(opts.hubDir, launchAgentsDir) : windows(opts.hubDir);
   if (flag === '--tray-status') {
-    await printStatus({ hubDir, configDir, value });
+    await printStatus(plat, opts);
     return true;
   }
   if (flag === '--no-autostart') {
-    try {
-      execFileSync('reg', ['delete', RUN_KEY, '/v', value, '/f'], { stdio: 'ignore' });
-      console.log('  Autostart: removed');
-    } catch {
-      console.log('  Autostart: not set');
-    }
+    console.log(plat.removeAutostart() ? '  Autostart: removed' : '  Autostart: not set');
     return true;
   }
-  const vbs = copyTray({ hubDir, port, appId, defaultPort, value });
-  console.log(`  Tray copy: ${path.dirname(vbs)}`);
+  console.log(`  Tray copy: ${copyTray(plat, opts)}`);
   if (flag === '--autostart') {
-    execFileSync('reg', ['add', RUN_KEY, '/v', value, '/t', 'REG_SZ', '/d', `wscript.exe "${vbs}"`, '/f'], { stdio: 'ignore' });
+    plat.addAutostart();
     console.log('  Autostart: on (starts at logon)');
   }
-  spawn('wscript.exe', [vbs], { detached: true, stdio: 'ignore' }).unref();
-  console.log('  Tray: started. Look for the hub icon in the notification area.');
+  plat.start();
+  console.log(`  Tray: started. Look for the hub icon in the ${plat.area}.`);
   return true;
 }
 
-module.exports = { runTrayCommand, runValue, appConfig };
+module.exports = { runTrayCommand, runValue, launchAgentLabel, launchAgentPlist, appConfig };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-hub",
-  "version": "1.5.1",
+  "version": "1.7.0",
   "description": "Unified hub for Claude Code tools — Marketplace + Kanban in one PWA",
   "main": "server.js",
   "bin": {
@@ -10,6 +10,7 @@
     "start": "node server.js",
     "dev": "node server.js --open",
     "test": "node --test test/*.test.js packages/claude-hub-sdk/test/*.test.js",
+    "test:e2e": "node --test --test-concurrency=1 test/e2e/keys.e2e.mjs",
     "update": "bash scripts/update-submodules.sh",
     "update:check": "bash scripts/update-submodules.sh --check",
     "lint": "npx @biomejs/biome check public/app.js server.js packages/claude-hub-sdk && npm run check:escaping && npm run check:security-lib",
@@ -45,10 +46,10 @@
   },
   "homepage": "https://github.com/NikiforovAll/claude-code-hub#readme",
   "dependencies": {
-    "claude-code-cost": "1.2.1",
-    "claude-code-kanban": "7.1.2",
-    "claude-code-marketplace": "1.3.1",
-    "claude-code-memory-explorer": "1.1.2",
+    "claude-code-cost": "1.3.0",
+    "claude-code-kanban": "7.3.0",
+    "claude-code-marketplace": "1.4.0",
+    "claude-code-memory-explorer": "1.2.0",
     "express": "^4.21.0",
     "open": "^10.1.0"
   },
@@ -65,6 +66,7 @@
   ],
   "devDependencies": {
     "@biomejs/biome": "^2.4.10",
-    "husky": "^9.1.7"
+    "husky": "^9.1.7",
+    "playwright-core": "^1.63.0"
   }
 }

package/packages/claude-hub-sdk/src/client.js

@@ -7,14 +7,8 @@
   const VARS_KEY = 'claude-hub:vars';
   const WELCOME_WAIT_MS = 2000;
 
-  // The hub's comboOf(). macOS turns Option+<key> into another character, so e.code is the fallback.
-  function comboOf(e) {
-    const lower = typeof e.key === 'string' ? e.key.toLowerCase() : '';
-    const m = /^(?:Key|Digit)([A-Z1-9])$/.exec(e.code || '');
-    const key = /^[a-z1-9]$/.test(lower) ? lower : m ? m[1].toLowerCase() : e.key;
-    const mods = [e.ctrlKey && 'ctrl', e.altKey && 'alt', e.shiftKey && 'shift', e.metaKey && 'meta'];
-    return [...mods, key].filter(Boolean).join('+');
-  }
+  // keys.js comes first in the served file. Required as a module, client.js loads it itself.
+  const { comboOf, keyParts } = typeof ClaudeHubKeys === 'object' ? ClaudeHubKeys : require('./keys');
 
   function isVars(v) {
     return (
@@ -33,6 +27,15 @@
 
   const strings = (list) => new Set(Array.isArray(list) ? list.filter((s) => typeof s === 'string') : []);
 
+  const isMac = (win) => /^Mac/i.test(win.navigator?.userAgentData?.platform || win.navigator?.platform || '');
+
+  const comboMap = (keys) =>
+    new Map(
+      keys && typeof keys === 'object' && !Array.isArray(keys)
+        ? Object.entries(keys).filter(([, c]) => c === null || (typeof c === 'string' && c))
+        : [],
+    );
+
   function createClaudeHub(win) {
     const doc = win.document;
     const framed = win.top !== win;
@@ -157,7 +160,11 @@
 
       function onWelcome(m) {
         if (m.protocol !== 1 || welcome) return;
-        welcome = { actions: strings(m.actions), themes: Array.isArray(m.themes) ? m.themes : [] };
+        welcome = {
+          actions: strings(m.actions),
+          keys: comboMap(m.keys),
+          themes: Array.isArray(m.themes) ? m.themes : [],
+        };
         forward = strings(m.forward);
         setStatus('live');
         if (welcome.themes.length) for (const fn of themesFns) fn(pickerThemes());
@@ -336,6 +343,21 @@
         forwards,
         // The combos forwards() matches, for a frame that tests keys with ClaudeHub.comboOf on its own.
         forwardCombos: () => (forward ? [...forward] : []),
+        // The keys of a hub action for a help row, in this system's names. A list of actions shares one
+        // row: ['Ctrl', 'Alt', '←/→']. [] when no key runs them; null before welcome, standalone, or
+        // for an action the hub did not list.
+        keyLabel(action) {
+          const ids = Array.isArray(action) ? action : [action];
+          if (!welcome || !ids.every((id) => welcome.keys.has(id))) return null;
+          const all = ids
+            .map((id) => welcome.keys.get(id))
+            .filter(Boolean)
+            .map((c) => keyParts(c, isMac(win)));
+          if (all.length < 2) return all[0] ?? [];
+          let n = 0;
+          while (n < all[0].length - 1 && all.every((p) => p.length - 1 > n && p[n] === all[0][n])) n++;
+          return [...all[0].slice(0, n), all.map((p) => p.slice(n).join('+')).join('/')];
+        },
         closeGuard(on) {
           post({ type: 'hub:closeGuard', on: !!on });
         },

package/packages/claude-hub-sdk/src/keys.js

@@ -0,0 +1,38 @@
+// Claude Code Hub SDK: the one rule that names a key press, shared by the hub page, client.js and
+// stub.js. The hub serves it to its page as /sdk/keys.js; mount() and sdk:sync put it in front of
+// client.js and stub.js, so an app still loads one file.
+// var, not const: the hub page and an app page each load it as a classic script, and a second
+// const declaration in the same page would throw.
+var ClaudeHubKeys = (() => {
+  'use strict';
+
+  // Modifiers in ctrl, alt, shift, meta order, joined by '+' to the key. macOS composes
+  // Option+<key> into a character (Option+1 is '¡', Option+P is 'π') and holding Control does not
+  // undo it, so e.key alone cannot name these presses there. e.code is the physical key, which is
+  // wrong for non-US layouts, hence only as a fallback. No fallback under AltGraph: Chromium sets it
+  // when AltGr types a character, and that press is text. Takes a real KeyboardEvent or a forwarded
+  // {key, code} payload; a payload without code degrades to key. A payload needs no AltGraph: the
+  // SDK forwards only a press whose key already names a bound combo.
+  // Self-contained on purpose: cck puts its source text into a sandboxed frame.
+  function comboOf(e) {
+    const lower = typeof e.key === 'string' ? e.key.toLowerCase() : '';
+    const m = !e.getModifierState?.('AltGraph') && /^(?:Key|Digit)([A-Z1-9])$/.exec(e.code || '');
+    const key = /^[a-z1-9]$/.test(lower) ? lower : m ? m[1].toLowerCase() : e.key;
+    const mods = [e.ctrlKey && 'ctrl', e.altKey && 'alt', e.shiftKey && 'shift', e.metaKey && 'meta'];
+    return [...mods, key].filter(Boolean).join('+');
+  }
+
+  // The keys of a combo as a help row shows them: ['Ctrl', 'Alt', 'P'], or ['⌃', '⌥', 'P'] on macOS.
+  // The {n} of a numbered combo reads 1…9.
+  function keyParts(combo, mac) {
+    const mods = mac
+      ? { ctrl: '⌃', alt: '⌥', shift: '⇧', meta: '⌘' }
+      : { ctrl: 'Ctrl', alt: 'Alt', shift: 'Shift', meta: 'Win' };
+    const named = { '{n}': '1…9', ArrowLeft: '←', ArrowRight: '→', ArrowUp: '↑', ArrowDown: '↓' };
+    return combo.split('+').map((k) => mods[k] ?? named[k] ?? (k.length === 1 ? k.toUpperCase() : k));
+  }
+
+  return { comboOf, keyParts };
+})();
+
+if (typeof module === 'object' && module.exports) module.exports = ClaudeHubKeys;

package/packages/claude-hub-sdk/src/server.js

@@ -1,5 +1,6 @@
 'use strict';
 
+const fs = require('node:fs');
 const path = require('node:path');
 
 // The hub hands this file to each app it spawns (HUB_SDK_SERVER), so it runs the hub's version, not
@@ -39,14 +40,20 @@ function answerHub() {
   process.channel.unref();
 }
 
+// What an app page loads as /vendor/claude-hub-sdk.js: keys.js, then client.js or stub.js.
+function bundle(file) {
+  const read = (f) => fs.readFileSync(path.join(__dirname, f), 'utf8');
+  return `${read('keys.js')}\n${read(file)}`;
+}
+
 // Mount before express.static: the hub's client must win over the app's stub in public/vendor.
 function mount(app) {
   answerHub();
-  const client = path.join(__dirname, 'client.js');
-  app.get('/vendor/claude-hub-sdk.js', (_req, res) => res.sendFile(client));
+  const client = bundle('client.js');
+  app.get('/vendor/claude-hub-sdk.js', (_req, res) => res.type('js').send(client));
   app.get('/hub-config', (_req, res) => {
     res.json({ enabled: !!process.env.CLAUDE_HUB, url: process.env.HUB_URL || null });
   });
 }
 
-module.exports = { mount };
+module.exports = { mount, bundle };

package/packages/claude-hub-sdk/src/stub.js

@@ -3,14 +3,8 @@
 ((root) => {
   'use strict';
 
-  // A copy of client.js comboOf(); a test checks they match.
-  function comboOf(e) {
-    const lower = typeof e.key === 'string' ? e.key.toLowerCase() : '';
-    const m = /^(?:Key|Digit)([A-Z1-9])$/.exec(e.code || '');
-    const key = /^[a-z1-9]$/.test(lower) ? lower : m ? m[1].toLowerCase() : e.key;
-    const mods = [e.ctrlKey && 'ctrl', e.altKey && 'alt', e.shiftKey && 'shift', e.metaKey && 'meta'];
-    return [...mods, key].filter(Boolean).join('+');
-  }
+  // keys.js comes first in the synced file. Required as a module, stub.js loads it itself.
+  const { comboOf } = typeof ClaudeHubKeys === 'object' ? ClaudeHubKeys : require('./keys');
 
   function createClaudeHub(win) {
     let hub = null;
@@ -42,6 +36,7 @@
         can: (action) => !!standaloneFn(action),
         forwards: () => false,
         forwardCombos: () => [],
+        keyLabel: () => null,
         closeGuard() {},
         openExternal(url) {
           win.open(url, '_blank', 'noopener');

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

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-hub",
-  "version": "0.2.0",
+  "version": "0.2.5",
   "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/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: hub-builder
-description: Build on and extend Claude Code Hub. Use when the user wants to patch or fork a built-in tool (Kanban, Cost, Marketplace, Memory), write a new app for a hub tab, connect apps through topics and actions, make a custom color theme, configure the hub (flags, config dirs, token), or fix a hub problem.
+description: Build on and extend Claude Code Hub. Use when the user wants to patch or fork a built-in tool (Kanban, Cost, Marketplace, Memory), write a new app for a hub tab, connect apps through topics and actions, make a custom color theme, configure the hub (flags, config dirs, token, hub keyboard shortcuts), or fix a hub problem.
 ---
 
 # Hub builder
@@ -23,7 +23,8 @@ The files under `references/` ship with the installed hub, so they match its ver
 | Flags, environment variables, `config.json`, the files the hub writes | `reference/configuration/` |
 | Switch between Claude config dirs | `guides/config-dirs/` |
 | The hub token, or exposing the hub to a network | `reference/security/` |
-| Keys the hub binds and keys the tools keep | `reference/shortcuts/` |
+| Rebind or turn off a hub key (`keys` in `config.json`) | [`references/keys.md`](references/keys.md) |
+| Look up a key: the hub's, a palette's, or a tool's own | `reference/shortcuts/` |
 | The embedded terminal in Kanban | `guides/terminal/` |
 | The project palette | `guides/projects/` |
 | Something is broken | `reference/troubleshooting/` |

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

@@ -14,7 +14,7 @@ Start with a patch. Move to a fork when the patch grows or breaks on each upgrad
 
 ## The apps entry
 
-`<hub-dir>/config.json` (`--hub-dir`, else `CLAUDE_HUB_DIR`, else `~/.claude-hub`) has `apps: [{id, path?, enabled?, port?}]`. Page: `extensibility/reference/apps-entry/`. The other keys of the file (`configDirs`, `activeConfigDir`, `terminal`) are in `reference/configuration/#the-config-file`; keep them as they are.
+`<hub-dir>/config.json` (`--hub-dir`, else `CLAUDE_HUB_DIR`, else `~/.claude-hub`) has `apps: [{id, path?, enabled?, port?}]`. Page: `extensibility/reference/apps-entry/`. The other keys of the file (`configDirs`, `activeConfigDir`, `terminal`, `keys`) are in `reference/configuration/#the-config-file`, and `keys` in [`keys.md`](keys.md); keep them as they are.
 
 To configure an extension:
 
@@ -40,7 +40,7 @@ Rules:
 
 - `path` is the folder with `hub-app.json`: absolute, or relative to the folder of `config.json`. The hub does not expand `~`.
 - A built-in id (`kanban`, `marketplace`, `cost`, `memory`) with a `path` runs that folder in place of the tool, with no second entry. A new id needs a `path` and runs as an extra tab.
-- Listed apps come first in list order, then the unlisted built-ins in default order. Tab order is also the `Alt+1`…`Alt+9` order.
+- Listed apps come first in list order, then the unlisted built-ins in default order. Tab order is also the `Alt+1`…`Alt+9` order (`⌃⌥1`…`⌃⌥9` on macOS).
 - `enabled: false` removes the app: no process, tab or port, and its actions and capabilities go to no one.
 
 ## The launch
@@ -68,7 +68,7 @@ The npm packages of the built-in tools do not ship `hub-app.json`. A patch or fo
 
 The page loads `/vendor/claude-hub-sdk.js` as the first element in `<body>`, a classic script, and calls `ClaudeHub.connect()`. Under the hub, `mount()` serves the hub's client at that URL, so the app always runs the hub's SDK. Alone, the app serves its own copy of the stub (`packages/claude-hub-sdk/src/stub.js`, copied by `npm run sdk:sync -- <app folder>` in a hub clone), which has the same API and does nothing. Page: `extensibility/reference/sdk/`.
 
-The SDK writes the hub's color variables (`--accent`, `--bg-surface`, …) on `document.body`, so the app's CSS reads them and follows every hub theme, the user's own themes too. `bindTheme` keeps light/dark and the color theme in step. `onActive` tells a hidden tab to pause polling. The SDK forwards the hub's keys by itself; an element that eats keys first, such as a terminal, asks `forwards(e)`.
+The SDK writes the hub's color variables (`--accent`, `--bg-surface`, …) on `document.body`, so the app's CSS reads them and follows every hub theme, the user's own themes too. `bindTheme` keeps light/dark and the color theme in step. `onActive` tells a hidden tab to pause polling. The SDK forwards the hub's keys by itself; an element that eats keys first, such as a terminal, asks `forwards(e)`. An app that uses a `Ctrl+Alt` combo of its own lists it in `keys.keeps` in `hub-app.json`, for example `{"keeps": ["ctrl+alt+n"]}`, so the hub does not bind it, and the user cannot give it to a hub action in `config.json` `keys`. The user can change the hub's own keys there, so an app takes them from `welcome.forward`, never from a fixed list, and a help dialog shows each hub key with `hub.keyLabel(action)`, for example `hub.keyLabel('hub.projectPicker')` → `['Ctrl', 'Alt', 'P']`. Page: `extensibility/reference/manifest/#kept-keys`.
 
 ## Connect to other tools
 
@@ -89,5 +89,5 @@ A replacement must keep what the original gave, or the other tools lose it: Kanb
 An extension is done when:
 
 - The hub startup log shows `<id> runs from <folder>` and no skip or conflict line for it.
-- Its tab shows at the expected `Alt+N`, and what it publishes, handles or provides reaches the other tools.
+- Its tab shows at the expected `Alt+N` (`⌃⌥N` on macOS), and what it publishes, handles or provides reaches the other tools.
 - It still runs alone, with the stub.