claude-code-hub 1.6.0 → 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:

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-hub",
-  "version": "1.6.0",
+  "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.2.0",
-    "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.

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

@@ -0,0 +1,50 @@
+# Change the hub keys
+
+The hub's own keys (switch tools, open the palettes) live in the `keys` block of `<hub-dir>/config.json` (`--hub-dir`, else `CLAUDE_HUB_DIR`, else `~/.claude-hub`). Each tool's own keys are outside it. Page: `reference/shortcuts/#change-the-keys`.
+
+## Steps
+
+1. Map each key the user asks for to an action in [Actions](#actions), and check its combo against [Rules](#rules). When a combo breaks a rule, tell the user why and offer one that passes.
+2. Read `config.json` and merge the entries into its `keys` block. Every other field stays byte for byte: the hub owns `configDirs`, `activeConfigDir` and `apps`.
+3. Restart the hub: it reads `keys` once, at startup. When the tray runs it, the user picks Quit in the tray menu and starts the hub again.
+4. Read the startup output, or `<hub-dir>/hub.log` when the tray started the hub. The hub logs each entry it drops as `<config.json path>: keys "<action>": … It keeps its default`. The reason is one of: not a combo, not a combo that ends in `+{n}`, `<combo> is kept by <app>`, `<combo> is already set for "<action>"`. An id that is not an action logs `keys "<id>" is not a hub action, ignored`.
+5. Read `GET http://localhost:<port>/api/config?token=<token>` (the token is in `<hub-dir>/token`).
+
+Done when the `keys` of `/api/config` holds every entry the user asked for, `null` ones too, and the startup output has no `config.json: keys` line. Then tell the user where to see it: each tool's help (`?`) shows the new hub keys and hides a hub row with no key, and the app launcher shows the tool-number keys.
+
+To go back to the defaults, remove the `keys` block and restart.
+
+## Example
+
+```json
+"keys": {
+  "hub.projectPicker": "ctrl+alt+o",
+  "hub.nextApp": "ctrl+alt+l",
+  "hub.prevApp": "ctrl+alt+h",
+  "hub.appByNumber": "ctrl+shift+{n}",
+  "hub.configDirPicker": null
+}
+```
+
+Ctrl+Alt+O opens the project palette, Ctrl+Alt+H and Ctrl+Alt+L move between tools, Ctrl+Shift+1 … 9 jumps to a tool by number, and the config-dir palette has no key. The app launcher keeps Ctrl+Alt+A.
+
+## Actions
+
+| Action | Default | Default on macOS |
+| --- | --- | --- |
+| `hub.projectPicker` | `ctrl+alt+p` | `ctrl+alt+p` |
+| `hub.configDirPicker` | `ctrl+alt+w` | `ctrl+alt+w` |
+| `hub.appLauncher` | `ctrl+alt+a` | `ctrl+alt+a` |
+| `hub.prevApp` | `ctrl+alt+ArrowLeft` | `ctrl+alt+ArrowLeft` |
+| `hub.nextApp` | `ctrl+alt+ArrowRight` | `ctrl+alt+ArrowRight` |
+| `hub.appByNumber` | `alt+{n}` | `ctrl+alt+{n}` |
+
+## Rules
+
+- **Form.** One or more of `ctrl`, `alt`, `shift`, `meta`, then one key, joined by `+`. The key is a letter, a digit 1 to 9, or a `KeyboardEvent.key` name (`ArrowUp`, `F2`, `PageDown`). On macOS `alt` is Option and `meta` is Command. Modifiers and letters take any case and order (`"Alt+Ctrl+O"` reads as `ctrl+alt+o`); a key name keeps its case (`PageDown`).
+- **`{n}`.** `hub.appByNumber` ends in `+{n}`, and the hub binds it for 1 to 9. It is the only action with `{n}`.
+- **`null`** leaves the action with no key.
+- **Taking a default.** A combo that is another action's default moves to the new action, and the other action has no key until it gets one: `"hub.nextApp": "ctrl+alt+a"` leaves the app launcher with no key. Say so to the user.
+- **Kept keys.** An app keeps the combos in `keys.keeps` of its `hub-app.json`, and the hub refuses them. Kanban keeps `ctrl+alt+n`, `ctrl+alt+r` and `ctrl+alt+s`.
+- **Tool keys.** A combo the hub binds never reaches the tool. Plain `ctrl+<key>` and `alt+<key>` combos belong to the tools and Claude Code's terminal (`ctrl+r`, `ctrl+c`, `alt+[`), so give the hub `ctrl+alt` or `ctrl+shift` combos.
+- **AltGr.** On a layout with AltGr (Polish, German), a `ctrl+alt` letter that types a character stays text, and that hub key does nothing. Offer another letter or a `ctrl+shift` combo.

package/public/app.js

@@ -1,4 +1,9 @@
 let apps = {};
+// bindings() builds it from apps and userKeys; setApps clears it.
+let keymap = null;
+// config.json `keys`, {actionId: combo | null}, from /api/config.
+let userKeys = {};
+const { comboOf, keyParts } = ClaudeHubKeys;
 let activeApp = null;
 // The app launcher's cursor starts here, so Ctrl+Alt+A then Enter goes back to the last tab.
 let previousApp = null;
@@ -11,6 +16,9 @@ const liveApps = new Map();
 // Apps whose next document the hub loads from an action URL.
 const linkLoads = new Set();
 const HUB_PROTOCOLS = [1];
+// Option+digit types a character on macOS (Option+5 is '[' on German layouts), so the tab numbers
+// there are Control+Option+digit.
+const IS_MAC = /^Mac/i.test(navigator.userAgentData?.platform || navigator.platform || '');
 // {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
 // global; the color theme is per config dir, and colorTheme is the last one picked anywhere, which
@@ -220,7 +228,8 @@ async function init() {
   showLoading();
   const res = await fetch('/api/config');
   const config = await res.json();
-  apps = config.apps;
+  userKeys = config.keys ?? {};
+  setApps(config.apps);
   defaultConfigDir = config.defaultConfigDir ?? null;
   activeConfigDir = config.activeConfigDir ?? null;
   applyTitle(config.activeConfigDir);
@@ -471,6 +480,7 @@ function onHello(appId, data) {
     type: 'hub:welcome',
     protocol: Math.max(...common),
     forward: Object.keys(bindings()),
+    keys: actionKeys(),
     themes: hubThemes,
     actions: Object.keys(actions),
   });
@@ -597,40 +607,70 @@ function handleForwardedKey(d) {
   bindings()[comboOf(e)]?.run();
 }
 
-// The one keymap. Its combo names are what welcome.forward lists for the apps.
-// inPalette: the binding still fires while the palette is open.
+// The hub's actions and their default combos. hub.appByNumber is a pattern: {n} is the tab number,
+// for the first nine. inPalette: the binding still fires while the palette is open. The ids are the
+// keys of config.json `keys`, listed again in lib/keymap.js.
+function hubActions() {
+  return [
+    { id: 'hub.projectPicker', combo: 'ctrl+alt+p', run: () => togglePalette('project'), inPalette: true },
+    { id: 'hub.configDirPicker', combo: 'ctrl+alt+w', run: () => togglePalette('configDir'), inPalette: true },
+    { id: 'hub.appLauncher', combo: 'ctrl+alt+a', run: () => togglePalette('app'), inPalette: true },
+    { id: 'hub.prevApp', combo: 'ctrl+alt+ArrowLeft', run: () => cycleTab(-1) },
+    { id: 'hub.nextApp', combo: 'ctrl+alt+ArrowRight', run: () => cycleTab(1) },
+    {
+      id: 'hub.appByNumber',
+      combo: `${IS_MAC ? 'ctrl+alt' : 'alt'}+{n}`,
+      run: (i) => switchTab(Object.keys(apps)[i]),
+      count: 9,
+    },
+  ];
+}
+
+// The one keymap, combo → binding. Its combos are what welcome.forward lists for the apps.
+// Built on first use after setApps, so a key press only looks a combo up. userKeys comes checked
+// from the server: null unbinds an action, and a combo the user sets is taken from the action
+// that has it by default.
 function bindings() {
-  const map = {
-    'ctrl+alt+p': { run: () => togglePalette('project'), inPalette: true },
-    'ctrl+alt+w': { run: () => togglePalette('configDir'), inPalette: true },
-    'ctrl+alt+a': { run: () => togglePalette('app'), inPalette: true },
-    'ctrl+alt+ArrowLeft': { run: () => cycleTab(-1) },
-    'ctrl+alt+ArrowRight': { run: () => cycleTab(1) },
-  };
-  Object.keys(apps)
-    .slice(0, 9)
-    .forEach((id, i) => {
-      map[`alt+${i + 1}`] = { run: () => switchTab(id) };
+  if (keymap) return keymap;
+  const tabs = Object.keys(apps).length;
+  const own = (b) => Object.hasOwn(userKeys, b.id);
+  const expand = (action) => {
+    const combo = comboFor(action);
+    if (!combo) return [];
+    if (!action.count) return [[combo, { ...action, combo }]];
+    return Array.from({ length: Math.min(action.count, tabs) }, (_, i) => {
+      const c = combo.replace('{n}', i + 1);
+      return [c, { ...action, combo: c, index: i, run: () => action.run(i) }];
     });
-  return map;
+  };
+  const entries = hubActions().flatMap(expand);
+  const userCombos = new Set(entries.filter(([, b]) => own(b)).map(([c]) => c));
+  keymap = Object.fromEntries(entries.filter(([c, b]) => own(b) || !userCombos.has(c)));
+  return keymap;
+}
+
+function comboFor(action) {
+  return Object.hasOwn(userKeys, action.id) ? userKeys[action.id] : action.combo;
+}
+
+// Action id → its combo, hub.appByNumber as its {n} pattern, or null when no key runs it. What
+// welcome.keys lists for the apps' help.
+function actionKeys() {
+  const bound = new Set(Object.values(bindings()).map((b) => b.id));
+  return Object.fromEntries(hubActions().map((a) => [a.id, bound.has(a.id) ? comboFor(a) : null]));
+}
+
+function setApps(list) {
+  apps = list;
+  keymap = null;
 }
 
-// The SDK's comboOf() is a copy of this: modifiers in ctrl, alt, shift, meta order, joined by
-// '+' to the key as bindingKey() names it.
-function comboOf(e) {
-  const mods = [e.ctrlKey && 'ctrl', e.altKey && 'alt', e.shiftKey && 'shift', e.metaKey && 'meta'];
-  return [...mods, bindingKey(e)].filter(Boolean).join('+');
+function appNumberCombo(i) {
+  return Object.values(bindings()).find((b) => b.id === 'hub.appByNumber' && b.index === i)?.combo;
 }
 
-// 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 carry these bindings there. e.code is the
-// physical key, which is wrong for non-US layouts, hence only as a fallback. Takes a real
-// KeyboardEvent or a forwarded {key, code} payload; a payload without code degrades to key.
-function bindingKey(e) {
-  const lower = typeof e.key === 'string' ? e.key.toLowerCase() : '';
-  if (/^[a-z1-9]$/.test(lower)) return lower;
-  const m = /^(?:Key|Digit)([A-Z1-9])$/.exec(e.code || '');
-  return m ? m[1].toLowerCase() : e.key;
+function comboLabel(combo) {
+  return keyParts(combo, IS_MAC).join(IS_MAC ? '' : '+');
 }
 
 function cycleTab(delta) {
@@ -904,6 +944,16 @@ async function restartFromPalette(id) {
   switchTab(id);
 }
 
+async function copyAppUrl(id) {
+  const url = apps[id].url;
+  try {
+    await navigator.clipboard.writeText(url);
+    setPaletteHint(`Copied ${url}`);
+  } catch (err) {
+    setPaletteHint(`Could not copy ${url}: ${err.message}`);
+  }
+}
+
 // `typed` is the trimmed query, `q` its lowercase form for matching.
 const PALETTE_MODES = {
   project: {
@@ -969,7 +1019,7 @@ const PALETTE_MODES = {
   app: {
     placeholder: 'Search apps...',
     label: 'Switch app',
-    hint: 'Enter switch · Ctrl+R restart the app',
+    hint: 'Enter switch · Ctrl+C copy the URL · Ctrl+R restart the app',
     empty: 'No matching app',
     rows: (_typed, q) => appRows(q),
     load: loadAppStats,
@@ -978,7 +1028,7 @@ const PALETTE_MODES = {
       return prev < 0 ? 0 : prev;
     },
     fillRow(li, row, q) {
-      li.append(appIcon(row.app), markedSpan('name', row.app.name, q));
+      li.append(appIcon(row.app), markedSpan('name', row.app.name, q), el('span', 'url', new URL(row.app.url).host));
       const s = palette.appStats?.[row.id];
       if (s?.slowMs) {
         const badge = el('span', 'slow', 'slow port');
@@ -988,11 +1038,15 @@ const PALETTE_MODES = {
       const stats = el('span', 'stats', s?.rss ? `${Math.round(s.rss / 1048576)} MB · ${s.cpu}%` : '');
       stats.title = 'Memory and CPU of the app process. Child processes are not counted. 100% is one core.';
       li.append(stats);
-      const key = row.id === activeApp ? 'active' : row.index < 9 ? `Alt+${row.index + 1}` : '';
+      const combo = appNumberCombo(row.index);
+      const key = row.id === activeApp ? 'active' : combo ? comboLabel(combo) : '';
       li.append(el('span', 'age', key));
-      li.append(rowButton('palette-restart', '↻', 'r', 'Restart the app (Ctrl+R)', `Restart ${row.app.name}`));
+      li.append(
+        rowButton('palette-copy', '⧉', 'c', 'Copy the URL (Ctrl+C)', `Copy the URL of ${row.app.name}`),
+        rowButton('palette-restart', '↻', 'r', 'Restart the app (Ctrl+R)', `Restart ${row.app.name}`),
+      );
     },
-    rowKeys: { r: (row) => restartFromPalette(row.id) },
+    rowKeys: { c: (row) => copyAppUrl(row.id), r: (row) => restartFromPalette(row.id) },
     commit(row) {
       closePalette();
       switchTab(row.id);
@@ -1143,7 +1197,7 @@ async function commitConfigDir(row) {
   if (target === palette.configDirs.active) return;
   showLoading();
   try {
-    apps = (await sendJson('POST', '/api/config-dirs/activate', { path: target })).apps;
+    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;
     activeConfigDir = target;
@@ -1190,11 +1244,13 @@ 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 && ['d', 'r'].includes(e.key.toLowerCase())) {
+    } else if (e.ctrlKey && !e.altKey && !e.shiftKey && !e.metaKey && ['c', 'd', 'r'].includes(e.key.toLowerCase())) {
+      const run = PALETTE_MODES[palette.mode].rowKeys?.[e.key.toLowerCase()];
+      // Ctrl+C with text selected in the input keeps the browser's copy.
+      if (e.key.toLowerCase() === 'c' && (!run || input.selectionStart !== input.selectionEnd)) return;
       // Ctrl+D would otherwise bookmark the page in Chrome and Firefox.
       // Ctrl+R would otherwise reload the hub page.
       e.preventDefault();
-      const run = PALETTE_MODES[palette.mode].rowKeys?.[e.key.toLowerCase()];
       const row = palette.rows[palette.sel];
       if (run && row && row.kind !== 'literal') run(row);
     }

package/public/index.html

@@ -272,6 +272,13 @@
 
     .palette-row .stats + .age { margin-left: 0; }
 
+    .palette-row .url {
+      color: var(--text-dim);
+      font-family: ui-monospace, monospace;
+      font-size: 12px;
+      align-self: center;
+    }
+
     .palette-row .slow {
       margin-left: 10px;
       padding: 0 6px;
@@ -307,6 +314,7 @@
     .palette-row.selected .palette-icon { color: var(--accent); }
 
     .palette-row .palette-remove,
+    .palette-row .palette-copy,
     .palette-row .palette-restart {
       margin-left: auto;
       padding: 0 6px;
@@ -322,13 +330,17 @@
 
     .palette-row:hover .palette-remove,
     .palette-row.selected .palette-remove,
+    .palette-row:hover .palette-copy,
+    .palette-row.selected .palette-copy,
     .palette-row:hover .palette-restart,
     .palette-row.selected .palette-restart { opacity: 1; }
 
     .palette-row .palette-remove:hover { color: #e5484d; }
 
-    .palette-row .age + .palette-restart { margin-left: 0; }
+    .palette-row .age + .palette-copy,
+    .palette-row .palette-copy + .palette-restart { margin-left: 0; }
 
+    .palette-row .palette-copy:hover,
     .palette-row .palette-restart:hover { color: var(--accent); }
 
     .palette-hint {
@@ -477,6 +489,7 @@
     <button class="update-toast-close" id="error-close" type="button" aria-label="Close">×</button>
   </div>
 
+  <script src="/sdk/keys.js"></script>
   <script src="/app.js"></script>
 </body>
 </html>

package/public/sw.js

@@ -1,5 +1,5 @@
-const CACHE_NAME = 'hub-shell-v2';
-const SHELL_ASSETS = ['/', '/index.html', '/app.js', '/manifest.json'];
+const CACHE_NAME = 'hub-shell-v3';
+const SHELL_ASSETS = ['/', '/index.html', '/sdk/keys.js', '/app.js', '/manifest.json'];
 
 self.addEventListener('install', (e) => {
   e.waitUntil(

package/server.js

@@ -10,6 +10,7 @@ const os = require('os');
 const path = require('path');
 const { actionTable } = require('./lib/actions');
 const { selectApps, loadApp, conflicts } = require('./lib/apps');
+const { userKeys } = require('./lib/keymap');
 const { stripCookie } = require('./lib/cookies');
 const { createNetGuard, KEEP_ALIVE_MS } = require('./lib/net-guard');
 const { ping, stats } = require('./lib/ipc');
@@ -131,6 +132,7 @@ function resolveHubConfig() {
   // 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;
   if (Array.isArray(saved.apps)) config.apps = saved.apps;
+  if (saved.keys !== undefined) config.keys = saved.keys;
   return { config, raw, fallback };
 }
 
@@ -164,6 +166,8 @@ if (!ENABLED_APPS.length) {
   process.exit(1);
 }
 const ACTIONS = actionTable(ENABLED_APPS);
+const { keys: USER_KEYS, lines: keyLines } = userKeys(hubConfig.keys, ENABLED_APPS);
+for (const line of keyLines) console.log(`${HUB_CONFIG_FILE}: ${line}`);
 // The first enabled app in tab order that declares the capability in its manifest.
 const provider = (cap) => ENABLED_APPS.find((a) => a.provides[cap]);
 const PROJECTS_APP = provider('projects');
@@ -886,6 +890,7 @@ app.get('/api/config', (_req, res) => {
     ...themeConfig(THEME_REGISTRY, { userFile: USER_THEMES_FILE }),
     apps: appsConfig(),
     actions: ACTIONS,
+    keys: USER_KEYS,
     activeConfigDir: hubConfig.activeConfigDir,
     defaultConfigDir,
   });
@@ -1083,6 +1088,8 @@ app.get('/api/resolve-path', (req, res) => {
   else res.json({ path: r.path });
 });
 
+const HUB_KEYS_JS = path.join(__dirname, 'packages', 'claude-hub-sdk', 'src', 'keys.js');
+app.get('/sdk/keys.js', (_req, res) => res.sendFile(HUB_KEYS_JS));
 app.use(express.static(path.join(__dirname, 'public')));
 
 // Children get HUB_URL at spawn and trust only that origin, so the first pool waits for the port