claude-code-hub 1.11.0 → 1.13.0

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

@@ -4,6 +4,8 @@
 ((root) => {
   'use strict';
 
+  // Holds {origin, vars}: the hub origin that sent the cached vars. Every config dir's app shares the
+  // hub's proxy port, so a page framed by something other than the hub would otherwise paint the hub's last theme.
   const VARS_KEY = 'claude-hub:vars';
   const WELCOME_WAIT_MS = 2000;
 
@@ -51,24 +53,33 @@
       return true;
     }
 
-    function adoptVars(vars) {
+    function adoptVars(vars, from) {
       if (!setVars(vars) && vars) return;
       try {
-        if (vars) win.localStorage.setItem(VARS_KEY, JSON.stringify(vars));
+        if (vars) win.localStorage.setItem(VARS_KEY, JSON.stringify({ origin: from, vars }));
         else win.localStorage.removeItem(VARS_KEY);
       } catch (_) {}
     }
 
-    function readVars() {
+    function readCache() {
       try {
-        const v = JSON.parse(win.localStorage.getItem(VARS_KEY));
-        return isVars(v) ? v : null;
+        const c = JSON.parse(win.localStorage.getItem(VARS_KEY));
+        return c && isVars(c.vars) ? c : null;
       } catch (_) {
         return null;
       }
     }
 
-    if (framed) setVars(readVars());
+    // The hub is the top window, also for a page framed inside another app's page, such as a cck
+    // pane. Firefox does not list the ancestors, so there any origin passes.
+    const ancestors = win.location?.ancestorOrigins;
+    const topOrigin = ancestors?.length ? ancestors[ancestors.length - 1] : undefined;
+    const hubOnTop = (o) => topOrigin === undefined || topOrigin === o;
+
+    if (framed) {
+      const cache = readCache();
+      if (cache && hubOnTop(cache.origin)) setVars(cache.vars);
+    }
 
     function connect({ standalone = {} } = {}) {
       if (hub) return hub;
@@ -98,8 +109,9 @@
         return typeof fn === 'function' ? fn : null;
       };
 
+      // The top window, not the parent: a page nested inside another app's page talks to the hub itself.
       function post(msg) {
-        if (origin) win.parent.postMessage(msg, origin);
+        if (origin) win.top.postMessage(msg, origin);
       }
 
       function setStatus(next) {
@@ -129,7 +141,7 @@
 
       function themeIn(p) {
         if (!p || typeof p !== 'object') return;
-        if (isVars(p.vars)) adoptVars(p.vars);
+        if (isVars(p.vars)) adoptVars(p.vars, origin);
         else if (!waiting()) adoptVars(null);
         lastTheme = p;
         applyMode(p);
@@ -172,7 +184,7 @@
       }
 
       function onMessage(e) {
-        if (!origin || e.source !== win.parent || e.origin !== origin) return;
+        if (!origin || e.source !== win.top || e.origin !== origin) return;
         const m = e.data;
         if (!m || typeof m.type !== 'string') return;
         switch (m.type) {
@@ -247,7 +259,10 @@
         .catch(() => ({}))
         .then((cfg) => {
           try {
-            if (framed && cfg?.enabled === true) origin = new URL(cfg.url).origin;
+            if (framed && cfg?.enabled === true) {
+              const hubOrigin = new URL(cfg.url).origin;
+              if (hubOnTop(hubOrigin)) origin = hubOrigin;
+            }
           } catch (_) {}
           if (!origin) {
             setVars(null);

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

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-hub",
-  "version": "0.2.6",
+  "version": "0.2.9",
   "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, hub keyboard shortcuts), 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, find, install, manage or develop an Extension (`claude-code-hub ext`), 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
@@ -18,6 +18,7 @@ The files under `references/` ship with the installed hub, so they match its ver
 | 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 |
+| Find, install, manage or develop an Extension (`claude-code-hub ext`) | [`references/extensions.md`](references/extensions.md) |
 | 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/` |

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

@@ -60,7 +60,7 @@ After a server change, restart the app: `Ctrl+Alt+A`, select it, `Ctrl+R`. After
 
 ## 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`, `keys.keeps`, `plugin` (`{id, path, install}` of a Claude Code plugin the app ships; the app launcher shows its state). 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/`.
+`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`, `keys.keeps`, `plugin` (`{marketplace, name, install?}` of a Claude Code plugin the app ships; the app launcher shows its state), `requires` (`{hub, node, apps}`), `listing` (the text of its registry page). To share an app, package it as an extension: [`extensions.md`](extensions.md). 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/`.
 

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

@@ -0,0 +1,56 @@
+# Extensions
+
+An extension is a hub app that the hub does not ship: a folder with a `hub-app.json`, often with a Claude Code plugin. Page: `extensibility/extensions/`.
+
+- `ext install <name>` finds the extension in the registry and installs the GitHub source it lists, as below. A folder named `<name>` in the current dir wins.
+- `ext install github:<owner>/<repo>[/<folder>][@<commit or branch>]` clones it into `<hub dir>/extensions/<id>` (needs `git`), installs its npm dependencies with install scripts off, and installs its plugin.
+- `ext install <dir>` makes it a *linked* extension: the hub runs it from that folder in place and copies nothing.
+
+`claude-code-hub ext` prints the commands and their options. In a clone of the hub, run `node server.js ext …` from the clone.
+
+## Find
+
+Fetch the registry index, `https://nikiforovall.blog/claude-code-hub/extensions.json`, and match the user's need against each entry's `tagline`, `description` and `tags`. Done when the user has the `page` link of every match, or knows the registry has none.
+
+## Install
+
+1. **Trust.** An extension runs as the user with no sandbox, and its plugin can run hooks in every Claude Code session. Tell the user that, name the repository and the plugin, and wait for a yes.
+2. **Run** the entry's `install` command, `claude-code-hub ext install <id>`. A failed step deletes the clone and leaves `config.json` as it was, so fix the cause (see Failures) and run the command again.
+3. **Restart** the hub. The extension starts with it and gets the next tab. `"deferredStart": true` in its `apps` entry makes it start only from the app launcher (`Ctrl+Alt+A`, select it, `Ctrl+S`).
+
+Done when `claude-code-hub ext list` shows the id with its source and its plugin `ok`.
+
+For an extension outside the registry: step 1, `claude-code-hub ext install github:<owner>/<repo>[/<folder>]`, step 3. For a folder on disk, the user's own included: step 1, `npm install` in the folder when its `package.json` has dependencies, `claude-code-hub ext install <dir>`, step 3.
+
+A linked extension lives in its folder: to move it, `ext remove <id>`, move the folder, `ext install` again.
+
+## Develop
+
+A linked extension is the dev loop: the hub runs the code where the user edits it.
+
+| Changed | Then |
+|---|---|
+| App code | Restart the app: `Ctrl+Alt+A`, select it, `Ctrl+R` |
+| Plugin | `claude-code-hub ext update <id>`, then a new Claude Code session. Claude Code runs a copy from its cache, and `update` reinstalls even at the same version |
+| `hub-app.json` | Restart the hub |
+
+The registry lists an extension whose manifest has `listing.tagline`. Page: `extensibility/reference/manifest/#listing`.
+
+## Manage
+
+- **Another config dir.** Claude Code loads plugins per config dir: `ext install <id> --dir <config dir>`. It works for a built-in tool too (`ext install kanban`), and is safe to run again.
+- **Update.** `ext update <id>` moves a GitHub extension to the tip of its branch (a pinned commit stays), installs its dependencies and plugin again, and goes back to the old commit when a check fails. Then `Ctrl+R` on its row and a new Claude Code session.
+- **Remove.** `ext remove <id>` removes the plugin, its marketplace and the `apps` entry, deletes the clone of a GitHub extension, keeps a linked folder, and needs a hub restart.
+- `ext update` and `ext remove` act only on entries that `ext install` added.
+
+## Failures
+
+- **⚠ on the app's row in the app launcher**, or a plugin state other than `ok` in `ext list` (`missing`, `disabled`, `mismatch`): a click on the ⚠ copies the `ext install <id>` command that fixes it.
+- **`Cannot register the plugin: marketplace "<name>" is registered from <path>`**: another folder already uses that marketplace name. The line ends with a `claude plugin marketplace remove` command; ask the user before running it, because it removes that marketplace's plugins.
+- **`it needs hub <x>` or `it needs Node <x>`**: upgrade the hub (`npm i -g claude-code-hub`) or Node. When it names an app that is off, turn that app on in the `apps` list of `config.json`.
+- **`git is not on PATH`**: install git, or clone the repo by other means and pass the folder.
+- **`git clone failed`**: the repo name is wrong, or the repo is private and git has no credentials for it.
+- **`Only a registry name, a github: source or a local folder installs`**: the source is `npm:` or a URL. Write it as `github:<owner>/<repo>[/<folder>]`.
+- **`Cannot read the registry`**: no network, or the site is down. Install with the entry's `source` from the registry page: `ext install github:…`, plus `@<sha>` for a pinned entry.
+- **`is not an app the hub runs, a folder, or an extension in the registry`**: the name is wrong. Find it in the registry (see Find).
+- **The app is missing from the launcher after a restart**: the hub startup log names each skipped app and why.