claude-code-hub 0.42.0 → 1.0.1

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

@@ -0,0 +1,371 @@
+// Claude Code Hub SDK: the app side of the hub protocol v1.
+// A classic script. Load it as the first element in <body>, with no defer or async,
+// so the cached theme is on the page before the first paint (protocol section 6, rule 3).
+((root) => {
+  'use strict';
+
+  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('+');
+  }
+
+  function isVars(v) {
+    return (
+      !!v &&
+      typeof v === 'object' &&
+      !Array.isArray(v) &&
+      Object.entries(v).every(([k, val]) => k.startsWith('--') && typeof val === 'string')
+    );
+  }
+
+  function sameVars(a, b) {
+    if (!a || !b) return a === b;
+    const keys = Object.keys(a);
+    return keys.length === Object.keys(b).length && keys.every((k) => a[k] === b[k]);
+  }
+
+  const strings = (list) => new Set(Array.isArray(list) ? list.filter((s) => typeof s === 'string') : []);
+
+  function createClaudeHub(win) {
+    const doc = win.document;
+    const framed = win.top !== win;
+    let appliedVars = null;
+    let hub = null;
+
+    function setVars(vars) {
+      const body = doc.body;
+      if (!body || sameVars(vars, appliedVars)) return false;
+      for (const k of Object.keys(appliedVars || {})) if (!vars || !(k in vars)) body.style.removeProperty(k);
+      for (const [k, v] of Object.entries(vars || {})) body.style.setProperty(k, v);
+      appliedVars = vars;
+      return true;
+    }
+
+    function adoptVars(vars) {
+      if (!setVars(vars) && vars) return;
+      try {
+        if (vars) win.localStorage.setItem(VARS_KEY, JSON.stringify(vars));
+        else win.localStorage.removeItem(VARS_KEY);
+      } catch (_) {}
+    }
+
+    function readVars() {
+      try {
+        const v = JSON.parse(win.localStorage.getItem(VARS_KEY));
+        return isVars(v) ? v : null;
+      } catch (_) {
+        return null;
+      }
+    }
+
+    if (framed) setVars(readVars());
+
+    function connect({ standalone = {} } = {}) {
+      if (hub) return hub;
+      const topics = new Map();
+      const activeFns = new Set();
+      const statusFns = new Set();
+      const handlers = new Map();
+      const pending = new Map();
+      const tokenWaiters = new Set();
+      const themesFns = new Set();
+      const queued = [];
+      // Topic → payload: the latest publish before welcome.
+      const outbox = new Map();
+      let status = 'connecting';
+      let origin = null;
+      let welcome = null;
+      let forward = null;
+      let themeBinding = null;
+      let lastTheme = null;
+      let swatchesPainted = false;
+      let nextId = 0;
+
+      const waiting = () => status === 'connecting' || status === 'waiting';
+      const standaloneFn = (action) => {
+        if (status !== 'standalone') return null;
+        const fn = (typeof standalone === 'function' ? standalone() : standalone)[action];
+        return typeof fn === 'function' ? fn : null;
+      };
+
+      function post(msg) {
+        if (origin) win.parent.postMessage(msg, origin);
+      }
+
+      function setStatus(next) {
+        status = next;
+        for (const fn of statusFns) fn(next);
+        if (waiting()) return;
+        for (const run of queued.splice(0)) run();
+        for (const [topic, payload] of outbox) hub.publish(topic, payload);
+        outbox.clear();
+      }
+
+      function emit(topic, payload) {
+        for (const fn of topics.get(topic) || []) fn(payload);
+      }
+
+      function themeKey(t) {
+        return `${t.theme}|${t.colorTheme}`;
+      }
+
+      function applyMode(p) {
+        if (!themeBinding || typeof p.theme !== 'string') return;
+        const cur = themeBinding.get();
+        const colorTheme = typeof p.colorTheme === 'string' ? p.colorTheme : cur.colorTheme;
+        if (cur.theme !== p.theme || cur.colorTheme !== colorTheme) themeBinding.set({ theme: p.theme, colorTheme });
+        themeBinding.last = themeKey(themeBinding.get());
+      }
+
+      function themeIn(p) {
+        if (!p || typeof p !== 'object') return;
+        if (isVars(p.vars)) adoptVars(p.vars);
+        else if (!waiting()) adoptVars(null);
+        lastTheme = p;
+        applyMode(p);
+        emit('theme.changed', p);
+      }
+
+      // The rules have the form scripts/generate-themes.mjs writes into each app's themes.css, so a
+      // built-in id gets the hub's swatch, which carries the user's change to that theme.
+      function pickerThemes() {
+        if (!swatchesPainted) {
+          swatchesPainted = true;
+          const vars = (s) =>
+            ['bg', 'accent', 'ink', 'border']
+              .filter((k) => typeof s?.[k] === 'string')
+              .map((k) => `--sw-${k}: ${s[k]};`)
+              .join(' ');
+          const style = doc.createElement('style');
+          style.textContent = welcome.themes
+            .map(
+              (t) =>
+                `.theme-swatch-${t.id} { ${vars(t.swatch?.dark)} }\nbody.light .theme-swatch-${t.id} { ${vars(t.swatch?.light)} }`,
+            )
+            .join('\n');
+          doc.head.appendChild(style);
+        }
+        return welcome.themes.map(({ id, label }) => ({ id, label }));
+      }
+
+      function onWelcome(m) {
+        if (m.protocol !== 1 || welcome) return;
+        welcome = { actions: strings(m.actions), themes: Array.isArray(m.themes) ? m.themes : [] };
+        forward = strings(m.forward);
+        setStatus('live');
+        if (welcome.themes.length) for (const fn of themesFns) fn(pickerThemes());
+        themesFns.clear();
+      }
+
+      function onMessage(e) {
+        if (!origin || e.source !== win.parent || e.origin !== origin) return;
+        const m = e.data;
+        if (!m || typeof m.type !== 'string') return;
+        switch (m.type) {
+          case 'hub:welcome':
+            return onWelcome(m);
+          case 'hub:event':
+            if (typeof m.topic !== 'string') return;
+            if (m.topic === 'theme.changed') return themeIn(m.payload);
+            return emit(m.topic, m.payload);
+          case 'hub:active':
+            for (const fn of activeFns) fn(!!m.active);
+            return;
+          case 'hub:action': {
+            const fn = handlers.get(m.action);
+            if (fn) fn(m.params || {}, { id: m.id });
+            else console.warn(`[claude-hub] no handler for action ${m.action}`);
+            return;
+          }
+          case 'hub:result': {
+            const resolve = pending.get(m.id);
+            if (!resolve) return;
+            pending.delete(m.id);
+            const { type, ...result } = m;
+            return resolve(result);
+          }
+          case 'hub:terminalToken':
+            for (const done of [...tokenWaiters]) done(typeof m.token === 'string' ? m.token : null);
+            return;
+        }
+      }
+
+      function forwards(e) {
+        return !!forward && forward.has(comboOf(e));
+      }
+
+      function onKeydown(e) {
+        if (!forwards(e)) return;
+        e.preventDefault();
+        post({
+          type: 'hub:keydown',
+          key: e.key,
+          code: e.code,
+          ctrl: e.ctrlKey,
+          alt: e.altKey,
+          shift: e.shiftKey,
+          meta: e.metaKey,
+        });
+      }
+
+      function run(action, params, resolve) {
+        if (status === 'live') {
+          const id = String(++nextId);
+          pending.set(id, resolve);
+          return post({ type: 'hub:invoke', id, action, params });
+        }
+        const target = standaloneFn(action)?.(params);
+        if (!target) return resolve({ ok: false, reason: 'unhandled' });
+        win.open(target, '_blank', 'noopener');
+        resolve({ ok: true, handledBy: 'standalone' });
+      }
+
+      win.addEventListener('message', onMessage);
+      doc.addEventListener('keydown', onKeydown);
+
+      const loaded =
+        doc.readyState === 'complete'
+          ? Promise.resolve()
+          : new Promise((r) => win.addEventListener('load', r, { once: true }));
+      const config = win
+        .fetch('/hub-config')
+        .then((r) => r.json())
+        .catch(() => ({}))
+        .then((cfg) => {
+          try {
+            if (framed && cfg?.enabled === true) origin = new URL(cfg.url).origin;
+          } catch (_) {}
+          if (!origin) {
+            setVars(null);
+            setStatus('standalone');
+          }
+        });
+
+      Promise.all([config, loaded]).then(() => {
+        if (!origin) return;
+        post({ type: 'hub:hello', protocol: [1], subscribes: [...topics.keys()] });
+        setStatus('waiting');
+        // A hub older than protocol v1 never answers. The app then runs as if alone, with no hub calls.
+        win.setTimeout(() => {
+          if (welcome) return;
+          adoptVars(null);
+          setStatus('unanswered');
+        }, WELCOME_WAIT_MS);
+      });
+
+      const topicFns = (topic) => {
+        if (!topics.has(topic)) topics.set(topic, new Set());
+        return topics.get(topic);
+      };
+
+      hub = {
+        get status() {
+          return status;
+        },
+        get themes() {
+          return welcome ? welcome.themes : [];
+        },
+        // True once /hub-config says a hub frames this page, whether or not it answers hello.
+        get inHub() {
+          return !!origin;
+        },
+        onStatus(fn) {
+          statusFns.add(fn);
+          return () => statusFns.delete(fn);
+        },
+        onActive(fn) {
+          activeFns.add(fn);
+          return () => activeFns.delete(fn);
+        },
+        // Calls fn once with the hub's themes as [{id, label}], after it paints their picker swatches
+        // (protocol section 6, rule 5). Never when standalone, with no welcome, or when the hub has no themes.
+        onThemes(fn) {
+          if (!welcome) {
+            themesFns.add(fn);
+            return () => themesFns.delete(fn);
+          }
+          if (welcome.themes.length) fn(pickerThemes());
+          return () => {};
+        },
+        subscribe(topic, fn) {
+          const fns = topicFns(topic);
+          fns.add(fn);
+          return () => fns.delete(fn);
+        },
+        bindTheme({ get, set }) {
+          topicFns('theme.changed');
+          themeBinding = { get, set, last: themeKey(get()) };
+          if (lastTheme) applyMode(lastTheme);
+          return function report() {
+            const cur = get();
+            const key = themeKey(cur);
+            if (key === themeBinding.last) return;
+            themeBinding.last = key;
+            // The inline vars are the old pick's and outrank the app's own themes.css. Until the hub
+            // echoes the new pick's vars, a script that reads computed colors now would get the old ones.
+            setVars(null);
+            post({ type: 'hub:theme', theme: cur.theme, colorTheme: cur.colorTheme });
+          };
+        },
+        handle(action, fn) {
+          handlers.set(action, fn);
+        },
+        // The topic must be in the app's manifest `publishes`. Before welcome, only the latest payload per topic waits.
+        publish(topic, payload) {
+          if (status === 'live') post({ type: 'hub:publish', topic, payload });
+          else if (waiting()) outbox.set(topic, payload);
+        },
+        invoke(action, params = {}) {
+          return new Promise((resolve) => {
+            if (waiting()) queued.push(() => run(action, params, resolve));
+            else run(action, params, resolve);
+          });
+        },
+        can(action) {
+          if (status === 'live') return welcome.actions.has(action);
+          return !!standaloneFn(action);
+        },
+        // For an element that eats keys before the document sees them, like a terminal.
+        forwards,
+        closeGuard(on) {
+          post({ type: 'hub:closeGuard', on: !!on });
+        },
+        // In the hub's installed PWA window, a framed page's own _blank open does nothing.
+        openExternal(url) {
+          if (origin) post({ type: 'hub:openExternal', url });
+          else win.open(url, '_blank', 'noopener');
+        },
+        // Resolves the hub's answer, or null standalone or after 3 s. The hub answers only its terminal provider.
+        terminalToken() {
+          return config.then(
+            () =>
+              origin &&
+              new Promise((resolve) => {
+                const done = (token) => {
+                  tokenWaiters.delete(done);
+                  win.clearTimeout(timer);
+                  resolve(token);
+                };
+                const timer = win.setTimeout(() => done(null), 3000);
+                tokenWaiters.add(done);
+                post({ type: 'hub:terminalToken' });
+              }),
+          );
+        },
+      };
+      return hub;
+    }
+
+    return { connect };
+  }
+
+  if (typeof module === 'object' && module.exports) module.exports = { createClaudeHub, comboOf };
+  else root.ClaudeHub = createClaudeHub(root);
+})(typeof window !== 'undefined' ? window : globalThis);

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

@@ -0,0 +1,30 @@
+'use strict';
+
+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
+// one the app shipped. An app run alone never loads it.
+
+// The hub spawns each app with an IPC channel. A loopback connect can fail while the app is fine,
+// so before the hub replaces an app it asks over the channel, which does not go through TCP.
+function answerHub() {
+  if (!process.channel) return;
+  process.on('message', (m) => {
+    if (m?.type === 'hub:ping') process.send({ type: 'hub:pong', id: m.id });
+  });
+  process.on('disconnect', () => process.exit(0));
+  // Listeners ref the channel. The app's own server keeps it alive, not the hub.
+  process.channel.unref();
+}
+
+// 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));
+  app.get('/hub-config', (_req, res) => {
+    res.json({ enabled: !!process.env.CLAUDE_HUB, url: process.env.HUB_URL || null });
+  });
+}
+
+module.exports = { mount };

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

@@ -0,0 +1,49 @@
+// Claude Code Hub SDK stub: what an app serves when no hub runs it. Under a hub, the hub hands the
+// app its real SDK (client.js) in place of this file. The API must match client.js; a test checks it.
+((root) => {
+  'use strict';
+
+  function createClaudeHub(win) {
+    let hub = null;
+    const off = () => {};
+
+    function connect({ standalone = {} } = {}) {
+      if (hub) return hub;
+      const standaloneFn = (action) => {
+        const fn = (typeof standalone === 'function' ? standalone() : standalone)[action];
+        return typeof fn === 'function' ? fn : null;
+      };
+      hub = {
+        status: 'standalone',
+        themes: [],
+        inHub: false,
+        onStatus: () => off,
+        onActive: () => off,
+        onThemes: () => off,
+        subscribe: () => off,
+        bindTheme: () => off,
+        handle() {},
+        publish() {},
+        invoke(action, params = {}) {
+          const target = standaloneFn(action)?.(params);
+          if (!target) return Promise.resolve({ ok: false, reason: 'unhandled' });
+          win.open(target, '_blank', 'noopener');
+          return Promise.resolve({ ok: true, handledBy: 'standalone' });
+        },
+        can: (action) => !!standaloneFn(action),
+        forwards: () => false,
+        closeGuard() {},
+        openExternal(url) {
+          win.open(url, '_blank', 'noopener');
+        },
+        terminalToken: () => Promise.resolve(null),
+      };
+      return hub;
+    }
+
+    return { connect };
+  }
+
+  if (typeof module === 'object' && module.exports) module.exports = { createClaudeHub };
+  else root.ClaudeHub = createClaudeHub(root);
+})(typeof window !== 'undefined' ? window : globalThis);

package/plugin/.claude-plugin/marketplace.json

@@ -0,0 +1,14 @@
+{
+  "name": "claude-code-hub",
+  "owner": {
+    "name": "NikiforovAll"
+  },
+  "description": "The plugin that ships with Claude Code Hub",
+  "plugins": [
+    {
+      "name": "claude-code-hub",
+      "source": "./plugins/claude-code-hub",
+      "description": "Claude Code Hub integration: a skill to build on the hub, with links to its docs and custom themes"
+    }
+  ]
+}

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

@@ -0,0 +1,8 @@
+{
+  "name": "claude-code-hub",
+  "version": "0.2.0",
+  "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

@@ -0,0 +1,30 @@
+---
+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.
+---
+
+# Hub builder
+
+Claude Code Hub runs Kanban, Cost, Marketplace and Memory as tabs of one window, and apps talk to it through the hub protocol. The docs site is the reference. Find the case below, fetch its page, and work from what the page says.
+
+The site documents the latest stable release. When the user's hub behaves differently from a page, trust the installed hub and say which version it is (`npm ls -g claude-code-hub`).
+
+## Docs
+
+Base URL: `https://nikiforovall.blog/claude-code-hub/`
+
+The files under `references/` ship with the installed hub, so they match its version. Read them before the site.
+
+| Case | Page |
+|---|---|
+| Extend the hub: patch or fork a built-in tool, write a new app, configure the `apps` entry, the manifest, the SDK, topics, actions, capabilities | [`references/extensibility.md`](references/extensibility.md). It names the docs page for each part |
+| The wire messages of the hub protocol | `reference/protocol/`, then `reference/architecture/` for processes and ports |
+| Start the hub, open it with its token, install it as an app | `getting-started/` |
+| 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/` |
+| The embedded terminal in Kanban | `guides/terminal/` |
+| The project palette | `guides/projects/` |
+| Something is broken | `reference/troubleshooting/` |
+| Make a custom color theme, or change a built-in one | [`references/themes.md`](references/themes.md) |

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

@@ -0,0 +1,93 @@
+# Extend the hub
+
+The hub runs each tool from a folder. An entry in the `apps` list of `config.json` points the hub at your folder, so you change or add a tool and leave the hub as it is. This file holds the mechanism. Each section names the docs page with the full rules, under `https://nikiforovall.blog/claude-code-hub/`.
+
+## Pick the way
+
+| Way | Use it when | You keep | Page |
+|---|---|---|---|
+| Patch | A few lines of a published tool change | A wrapper project: the npm package pinned to the hub's exact version, `patch-package`, a `hub-app.json` | `extensibility/patch/`, example `extensibility/examples/compact-rows/` |
+| Fork | A new page, a new route, or changes in many parts of a tool | A clone of the tool's repo at the tag the hub runs, with a new or the same id | `extensibility/fork/`, example `extensibility/examples/task-board/` |
+| New app | The tool does a different job | Your own server, page and manifest | `extensibility/new-app/`, example `extensibility/examples/inspector/` |
+
+Start with a patch. Move to a fork when the patch grows or breaks on each upgrade. A patch can stop applying when the pinned version changes, and `npm install` still succeeds unless the `postinstall` script has `--error-on-fail`.
+
+## 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.
+
+To configure an extension:
+
+1. Open `config.json` and add the `apps` key if it is not there.
+2. Add one entry per change:
+
+   ```json
+   {
+     "apps": [
+       { "id": "kanban-patched", "path": "C:/dev/kanban-patched" },
+       { "id": "kanban", "enabled": false },
+       { "id": "inspector", "path": "C:/dev/inspector", "port": 3560 }
+     ]
+   }
+   ```
+
+   The first two entries replace Kanban: the patched copy runs under its own id, and the original is off, so the copy gets Kanban's capabilities. A built-in id with a `path` does the same in one entry (see the rules below). The third adds a new app as a tab, on a fixed port. To run a fork next to the original, keep `{ "id": "kanban" }` enabled.
+3. Make the `id` in the folder's `hub-app.json` the same as the entry's `id`, or the hub skips the app.
+4. Run `npm install` in the app folder.
+5. Restart the hub, because it reads the list at startup only. The startup log names each skipped app and why, and each conflict.
+
+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.
+- `enabled: false` removes the app: no process, tab or port, and its actions and capabilities go to no one.
+
+## The launch
+
+For each config dir, the hub runs `run.entry` with its own Node and an IPC channel, and restarts it up to 5 times in 60 s. The working dir is the hub's folder, so the app resolves its files from `__dirname`. Page: `extensibility/reference/apps-entry/#launch`.
+
+The app server must:
+
+1. Call `require(process.env.HUB_SDK_SERVER).mount(app)` before it serves static files, when the variable is set.
+2. Listen on `PORT` (`0`, any free port) and `HOST`, and print one stdout line that matches `/running at http:\/\/localhost:(\d+)/i` with the real port, within 20 s.
+3. Allow framing by the hub origin: no `X-Frame-Options`, no blocking `frame-ancestors`.
+4. Work with no hub.
+
+The browser sees the app on a proxy port (`--<id>-port`, else the entry's `port`, else `run.defaultPort`). That port is the app's origin and keys its `localStorage`, so a busy port falls back to a random one and the app starts with empty storage for that run. Give each app its own `defaultPort`.
+
+After a server change, restart the app: `Ctrl+Alt+A`, select it, `Ctrl+R`. After a change in `public/`, reload the page. A change to `hub-app.json` or `config.json` needs a hub restart.
+
+## The manifest
+
+`hub-app.json` declares how to run the app and what it offers: `manifest: 1`, `id`, `name`, `icon` (a Lucide name), `run.entry` (inside the folder; a path into `node_modules` is fine), `run.defaultPort`, `loading.verbs`, `publishes`, `actions.handles`, `provides`. The hub reads it before the app runs and skips the app, with a log line, when it breaks a rule. Page: `extensibility/reference/manifest/`.
+
+The npm packages of the built-in tools do not ship `hub-app.json`. A patch or fork starts from the tool's manifest in its GitHub repo and changes `id`, `name` and `run.entry`. Page for what each built-in declares: `extensibility/reference/built-in/`.
+
+## The SDK
+
+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)`.
+
+## Connect to other tools
+
+Apps never talk to each other directly. Each page talks to the hub page through the SDK, and the hub passes the message on. There is no server-to-server channel. Page: `extensibility/reference/connect/`.
+
+- **Topics: one to many, sticky.** The hub keeps the last value and replays it when an app connects or comes on screen. The hub publishes `project.changed` (`{project, encoded, name}` or `null`) and `theme.changed`. An app publishes only the topics its manifest lists in `publishes`. Kanban publishes `session.changed`. Subscribe before the page's `load` event, because the SDK sends the topic list with its hello.
+- **Actions: one caller, one handler.** The caller names the action, not the app: `hub.can(name)` decides whether to show the control, `hub.invoke(name, params)` routes it and resolves when routed. The handler declares it in `actions.handles` with a `url` template; with `mode: "message"` a live page gets it through `hub.handle`, else the hub loads the URL, so the handler also reads the params from its query string. The built-in actions are `session.cost` (Cost), `project.plugins` (Marketplace) and `project.memory` (Memory Diagnoser).
+- **Capabilities: one provider per job.** `provides.projects.path` answers the project palette's list; `provides.terminal.liveWork` answers the open terminals and makes the app the terminal provider, which gets the terminal env and token. Kanban provides both today.
+
+## First in tab order wins
+
+When two enabled apps declare the same capability, action or port, the first in tab order gets it, and the hub logs the conflict at startup. Use this to take over a built-in action or capability: put your app first, or turn the built-in off.
+
+A replacement must keep what the original gave, or the other tools lose it: Kanban's `projects`, `terminal` and `session.changed`, and each other tool's action. A tool that runs next to the original can leave these to it. Page: `extensibility/fork/#what-the-built-in-tool-gives`.
+
+## Check
+
+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.
+- It still runs alone, with the stub.

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

@@ -0,0 +1,57 @@
+# Custom themes
+
+The hub is the theme source for every app in its tabs. It sends the colors of the current theme to each app, so a custom theme reaches all apps with no app change. Colors the apps own (`--success`, `--warning`, `--error`, chart colors, fonts) stay out of a theme.
+
+## Where the file lives
+
+`<hub-dir>/themes.json`, where the hub dir is `--hub-dir`, else `CLAUDE_HUB_DIR`, else `~/.claude-hub`. The file is a JSON array of themes. Create it when it is missing. The hub reads it on each page load, so an edit applies when the user reloads the hub page.
+
+## Three kinds of entry
+
+Each entry has an `id` (`^[a-z0-9-]{1,32}$`), a `label` for the picker, and a `dark` and a `light` object of colors.
+
+1. **Tweak a built-in theme.** Use the built-in id. The entry starts from that theme, so it holds only the colors it changes, in either mode or both.
+   ```json
+   { "id": "ember", "dark": { "ember": "#3b82f6", "emberGlow": "#93c5fd" } }
+   ```
+2. **Base a new theme on a built-in one.** A new id plus `"extends": "<built-in id>"`. It starts from that theme, and its colors win. A mode it leaves out comes from the base.
+   ```json
+   { "id": "deep-sea", "label": "Deep Sea", "extends": "nord", "dark": { "field": "#0b1220", "surface": "#111a2e" } }
+   ```
+3. **New theme from scratch.** A new id with no `extends`. Both `dark` and `light` hold every required color below.
+
+Built-in ids: `ember` (the default), `gruvbox`, `catppuccin`, `tokyo-night`, `solarized`, `dracula`, `nord`, `rose-pine`, `everforest`, `kanagawa`, `one-dark`, `night-owl`, `monokai`, `github`, `ayu`, `vitesse`, `synthwave`.
+
+## Colors
+
+The keys are palette roles. The hub maps each role to the CSS variable the apps read.
+
+| Role | CSS variable | Paints |
+|---|---|---|
+| `ember` | `--accent` | The accent: active items, primary buttons, focus |
+| `emberGlow` | `--accent-text` | Accent used as text, so it must read on `surface` |
+| `emberDim` | `--accent-dim` | A faint accent fill, usually the accent at 0.18–0.25 alpha |
+| `field` | `--bg-deep` | The page background |
+| `surface` | `--bg-surface` | Panels and cards |
+| `elevated` | `--bg-elevated` | Raised surfaces |
+| `hover` | `--bg-hover` | The hover state |
+| `border` | `--border` | Borders and dividers |
+| `ink1` | `--text-primary` | Main text |
+| `ink2` | `--text-secondary` | Secondary text |
+| `ink3` | `--text-tertiary` | Tertiary text |
+| `inkMuted` | `--text-muted` | Muted text |
+| `sidebar` | `--sidebar-bg` | Optional. The sidebar background |
+| `sidebarItem` | `--sidebar-item-bg` | Optional. A sidebar item background |
+
+The hub derives `--accent-glow` from `ember`, and the picker swatch from `surface`, `ember`, `ink1` and `border`.
+
+A value is a hex color (`#rgb`, `#rrggbb`, `#rrggbbaa`), or `rgb()`, `rgba()`, `hsl()`, `hsla()` or `oklch()`.
+
+For a from-scratch theme, copy a built-in palette with the same feel and change it, so both modes keep their contrast. `lib/themes.json` in the hub package holds every built-in palette: `$(npm root -g)/claude-code-hub/lib/themes.json` for a global install.
+
+## Check
+
+The hub skips an entry that breaks a rule and prints why in its console, naming the theme and the role. A theme is done when:
+
+- The hub console shows no skip line for it after a page reload.
+- It shows in the theme picker of each tab, and picking it repaints every tab in both modes.