claude-code-hub 1.5.1 → 1.7.0

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
@@ -1104,7 +1111,7 @@ const onReady = (actual) => {
 if (!TRAY_FLAG) {
   liveHub(HUB_DIR, HUB_TOKEN).then((running) => {
     if (!running) {
-      watchStdin();
+      if (!process.argv.includes('--detached')) watchStdin();
       listenProxies();
       listenWithFallback(app, HUB_PORT, onReady, '');
       return;