Skip to content

Hub protocol v1

This spec is the contract between the hub and an app that runs in one of its tabs. It covers the launch, the SDK, the postMessage protocol, the theme variables and the app manifest. For an overview, see Architecture.

Stable. Protocol version 1, manifest format 1. The protocol before v1 (v0) is not supported (Compatibility).

Version Where Changes when
Protocol hello.protocol, welcome.protocol A change that an app or hub of the same version cannot ignore
Manifest hub-app.json manifest A field that the hub must read in a new way
SDK version in packages/claude-hub-sdk/package.json, also in the stamp line of each synced copy. Semver, with each version in CHANGELOG.md Any change to the SDK source. A test fails when the source changes and the version does not
  1. Additive changes keep the version. A new message type, topic, action, optional payload field or manifest field is not a new protocol version. The hub and the app ignore a type or field they do not know (Message rules).
  2. A breaking change bumps the version. The next version is 2. An app lists every version it speaks in hello, and the hub answers with the highest version that both sides speak (Handshake).
  3. The hub supplies the SDK. Under the hub, an app runs the hub’s SDK, so the app and the hub always speak the same version (SDK).
Term Meaning
Hub The hub server and the hub page that holds the iframes
App A web app that the hub spawns and shows in an iframe
App id A name that matches ^[a-z][a-z0-9-]{0,31}$, unique in the hub, for example cost. hub is reserved
Pool The set of app processes for one Claude config dir
Framed The app document is not the top window (window.top !== window)
Nested page An app document framed inside another app’s document, for example a page that a Kanban pane shows. Its top window is the hub, but its parent is not (Nested pages)
Current document The document that the iframe holds now. A reload or a config-dir switch starts a new one
Live The iframe sent hub:hello after its last load event

The hub spawns each enabled app once per config dir. It runs run.entry from the manifest with Node and --max-http-header-size=65536, with the hub root as the working directory. An app must resolve its own files from its script path, not from the working directory. The env vars:

Env Value
CLAUDE_HUB 1
HUB_URL The hub origin, http://localhost:<hub port>, with the port the hub is bound to. The hub binds its port before it starts any app
CLAUDE_CONFIG_DIR The Claude config dir of this pool
PORT 0. The app binds any free port
HOST, ALLOWED_HOSTS The hub’s bind rules. The app must use them as they are
HUB_SDK_SERVER The absolute path of the hub’s server SDK, packages/claude-hub-sdk/src/server.js. Always set (SDK)
HUB_APP_SETTINGS The app’s settings as JSON, {key: value}, at spawn. Set only for an app with settings. A later change reaches the page, not this env
Capability env Only for the provider of that capability, for example CCK_TERMINAL and CCK_TERMINAL_TOKEN for terminal

The app reads these once at start. A new config dir gets a new process. If an app exits, the hub starts it again, up to 5 times in 60 seconds.

When the app listens, it prints one stdout line with its real port:

<Name> running at http://localhost:<port>
  • The hub matches it with /running at http:\/\/localhost:(\d+)/i. Print no other line that matches.
  • End the line with a newline: the hub reads stdout line by line.
  • The hub waits 20 s for the ready lines of a config dir’s apps, then shows the apps that are ready.

The hub spawns the app with a Node IPC channel. The server SDK’s mount() does all of this:

  • The app answers {type: 'hub:ping', id} with {type: 'hub:pong', id}.
  • The app answers {type: 'hub:stats', id} with {type: 'hub:stats', id, rss, cpu}: the memory of its own process in bytes and its CPU in percent of one core, sampled over 250 ms. The app launcher shows them. An app that does not answer within 1 s shows no stats.
  • The app exits when the channel closes, and unrefs the channel.

After 3 failed connects to the app, the hub pings it:

Answer What the hub does
Pong in 3 s The loopback dropped the connects. The hub keeps the app, and the request retries for up to 30 s more.
No pong The hub replaces the app.
Pong, but connects still fail after 30 s The hub replaces the app.

The hub serves each app through a proxy port per app id. The proxy origin is the app’s origin in the browser, so it keys the app’s localStorage. So each app must declare a fixed run.defaultPort, different from the other apps.

The hub takes the first port that is set:

  1. The --<id>-port flag.
  2. The port of the app’s entry in the apps list of the hub’s config.json. The user sets it, not the app, so it overrides the manifest.
  3. run.defaultPort from the manifest.

When that port is taken, the hub uses a random free port for this run, and the app starts with empty localStorage for that run.

The app must allow framing by the hub origin: it must not send an X-Frame-Options header or a frame-ancestors rule that blocks it.

The hub ships the SDK and hands it to each app it spawns, so the app runs the hub’s version. The SDK has three files in packages/claude-hub-sdk/src:

File Runs in Does
server.js The app server, under the hub mount(app) answers hub:ping and hub:stats (Launch), and registers GET /hub-config and GET /vendor/claude-hub-sdk.js, which serves client.js
client.js The app page, under the hub The app side of this spec. It sets window.ClaudeHub
stub.js The app page, standalone The same API as client.js, with no hub. It never fetches /hub-config and sends no message
  1. Mount under the hub only. The app server calls require(process.env.HUB_SDK_SERVER).mount(app) when HUB_SDK_SERVER is set, before its static files, so the route for client.js wins over the stub.
  2. Ship the stub. The app serves stub.js as its own public/vendor/claude-hub-sdk.js. npm run sdk:sync -- <app id | dir> in the hub repo copies it there, with a stamp line that names the SDK version and hash. It also copies client.js to test/vendor/claude-hub-sdk.js, for the app’s tests. The app does not ship that copy.
  3. Load it first. The page loads /vendor/claude-hub-sdk.js as a classic script, the first element in <body>, with no defer or async (Theme, rule 3).
  4. Same API. The stub and the client have the same functions. The hub’s tests check this.

The app’s page code calls ClaudeHub.connect() and uses the returned object: subscribe, publish, bindTheme, onThemes, onActive, onStatus, handle, invoke, can, forwards, forwardCombos, keyLabel, voiceCommands, closeGuard, openExternal and terminalToken. It works the same with the stub and the client.

Route Response
GET /hub-config {enabled: <CLAUDE_HUB is set>, url: HUB_URL}

mount() registers this route, so it exists only under the hub. The client fetches it once at start. It is how the app learns that it is under the hub and which origin to trust.

Each message is {type: 'hub:<name>', …payload}, sent with postMessage.

App side:

  1. Until /hub-config resolves with enabled: true, the app sends nothing and drops every message.
  2. The app talks to the hub only when the hub is its top window. Where the browser lists location.ancestorOrigins, the last entry must be the origin of /hub-config’s url; when it is not, the app runs standalone at once. Firefox has no such list, so there the app sends hello and waits.
  3. The app accepts a message only when e.source === window.top and e.origin is the origin of /hub-config’s url.
  4. The app posts only to window.top, with that origin as the target origin. For an app in a tab, window.top is window.parent.
  5. Every apply must be idempotent. The hub can send the same state more than once.

Hub side:

  1. The hub names the sender by e.source: the iframe whose contentWindow sent it. It drops a message when e.origin is not that app’s origin. A payload never names the sender.
  2. A sender that is not an app iframe is a nested page when its parent chain reaches an app iframe. The hub names it by e.origin, the app whose origin it is, and keeps the window from its hello. It drops every other sender (Nested pages).
  3. The hub posts to an iframe, or to a nested page’s window, with that app’s exact origin.
  4. The hub ignores a type it does not know. The app must do the same.
Direction Type Payload
App → hub hub:hello {protocol: [1], subscribes?: string[]}
Hub → app hub:welcome {protocol: 1, forward: string[], keys?: {[action]: string | null}, themes: Theme[], actions: string[], origins?: string[], settings?: {[key]: boolean | string}}
  1. The app sends hello after its own load event, once /hub-config resolves with enabled: true and its message listeners are in place. It sends it once per document.
  2. protocol lists the versions the app speaks. The hub answers with the highest version in both lists. When there is none, the hub does not answer, and the app works as an app with no welcome (No welcome).
  3. A valid hello makes the app live. The hub clears the live state on each iframe load event, because e.source stays the same object across reloads. Every new document, from a reload or from a src that the hub sets, ends in a load. Because hello comes after the app’s load, the hub always sees load first, and a late hello from the old document is cleared by that load.
  4. After welcome, the hub sends the current state: a hub:event for each sticky topic in subscribes that has a value (Events), and hub:active. An app gets no theme or project for a topic it did not subscribe to.
  5. welcome fields:
    • forward: the key combos the hub binds (Keys).
    • keys: the combo of each hub action, for an app’s help (Keys, rule 5).
    • themes: the list for the theme picker (Theme).
    • actions: the actions that an enabled app handles (Actions).
    • origins: the origin of each enabled app. A link to one of them stays in the hub (Links). A hub older than this field does not send it.
    • settings: the values of the app’s own settings (Settings). {} for an app with none. A hub older than this field does not send it.
    • voice: with voice on, {say, help} for each voice command whose action this app handles, for the app’s help. say is the phrase after “hub”. [] with voice off. A hub older than this field does not send it.

An app page can be framed inside another app’s page, for example a Swarm page in a Kanban pane. It is served from the app’s own proxy origin, so it runs the hub’s SDK and talks to the hub through window.top. The app’s tab, if it has one, stays a separate document with its own state.

Message Nested page
hub:hello, hub:welcome Yes. The hub keeps the page’s window until it closes or the config dir changes
hub:event theme.changed Yes, after welcome and on every change
hub:theme Yes. The user’s pick reaches every tab and every nested page
hub:invoke, hub:result Yes. The result goes to the nested page
hub:keydown Yes, for the combos in welcome.forward, as from a tab
hub:openExternal Yes
hub:settings Yes, the settings of the app the page belongs to
Other topics, hub:publish No. Topics such as project.changed and session.changed belong to the tab
hub:active No. It names the tab on screen; a nested page is on screen when its parent shows it
hub:action No. The hub routes an action to the handler’s tab
hub:closeGuard, hub:terminalToken No. The hub keeps them per app id, for the tab

A page with no hub:active must count itself active, as the SDK’s onActive does by never calling back.

While a nested page has focus, its key presses never reach the app page around it, the host. The host can claim the presses it acts on, such as Kanban’s Alt+W that closes the pane. These messages go between the nested page and its host, not through the hub, and each side checks the other’s window and origin.

Direction Message Payload
Host → page hub:hostKeys {keys}, the claims. The host sends it when the frame loads and again when its claims change. Each message replaces the last
Page → host hub:hostReady {plainKeys?}, once per document, on the first hub:hostKeys. The host can then hide a hint that its keys are off. plainKeys, a list of e.key values, asks for the host’s claims on those keys without Ctrl, Alt or Meta too
Page → host hub:hostKey {key, code, ctrl, alt, shift, meta}, a claimed press. The host replays it as its own press

A claim names a press by its physical key, {ctrlKey?, altKey?, shiftKey?, metaKey?, key: 'Unidentified', code}, or by its character, {…, key, code: ''}. A press matches when its code or its lowercased key, with the same modifiers, equals the claim’s. A press under AltGraph matches by character only. The page sends a press to the hub first when its combo is in welcome.forward. It keeps a press in a text field and a press it already handled (defaultPrevented), and calls preventDefault() on a press it sends. Kanban claims only presses with Ctrl, Alt or Meta, so the page keeps its own letter keys and Escape. A page that sent plainKeys: ['\\'] also gets Kanban’s claims on \ (sidebar), and names only keys it leaves free.

The hub is the theme source. Under the hub, an app takes its colors from the hub. Its own theme CSS is for standalone use only.

Direction Type Payload
App → hub hub:theme {theme: 'light' | 'dark', colorTheme?}: the user changed the theme in the app
Hub → app hub:event theme.changed {theme, colorTheme, vars?}
  • vars: the core variables for the current theme and mode, for example {"--accent": "#e86f33", …}. The hub omits it when it has no theme registry. A theme.changed with no vars means: remove the inline vars and use the app’s own theme CSS.
  • Theme in welcome.themes: {id, label, swatch: {dark, light}}, where each swatch is {bg, accent, ink, border}.
  • The id of the default theme, Ember, is ember.
Group Variables
Accent --accent, --accent-text, --accent-dim, --accent-glow
Background --bg-deep, --bg-surface, --bg-elevated, --bg-hover
Border --border
Text --text-primary, --text-secondary, --text-tertiary, --text-muted
Sidebar --sidebar-bg, --sidebar-item-bg. Only some themes set them

The hub does not theme semantic colors (--success, --warning, --error), chart series colors or fonts. The app owns them.

  1. Apply on body. The app writes vars as inline custom properties on document.body, so they win over every selector rule. It also sets its own mode class and theme attribute for the rest of its styles.
  2. Apply on change only. When vars equal the last set it applied, the app does nothing.
  3. Paint the cached set first. The app keeps the last vars in localStorage, with the hub origin that sent them.
    • When framed, it applies them synchronously at start, before the first paint and before /hub-config resolves. Where the browser lists location.ancestorOrigins, it applies them only when the last entry is the cached hub origin, so a page framed by something other than the hub does not paint the hub’s theme. So the code runs from a classic script that is the first element in <body>, before the app’s own scripts, with no defer or async. In <head>, document.body does not exist yet.
    • Standalone, it never applies them: a standalone tab can share the origin with the proxy.
    • When the hub sends no vars, or sends no welcome within 2 s of hello, the app removes the cached set from the page and from localStorage. Until then, it keeps the cached set.
  4. Derive extras. An app computes any extra variable from the core set in its own CSS, for example --chart-fill: color-mix(in srgb, var(--accent) 32%, transparent), so it follows a theme it does not know. It declares the extra on body, not :root: var() resolves where the property is declared, and the inline vars are on body.
  5. Picker. Under the hub, the app’s theme picker lists welcome.themes, which include the user’s own themes, with the hub’s swatches. The SDK’s onThemes(fn) calls fn once with [{id, label}] after it adds a style sheet of .theme-swatch-<id> and body.light .theme-swatch-<id> rules that set --sw-bg, --sw-accent, --sw-ink and --sw-border. Standalone, it lists the app’s own themes.
  6. Report. When the user picks a theme in the app, the app sends hub:theme and applies what it has: its own CSS for a theme it knows, else the swatch only. The hub stores the theme and sends it as theme.changed with vars to every live app, the sender included.
  7. Unknown id standalone. An app that stored a hub-only theme id shows its default theme when it runs standalone.
  8. Subscribe. An app that applies the theme lists theme.changed in hello.subscribes, so it gets the theme as a sticky hub:event after welcome. The SDK’s bindTheme adds the topic. Call it right after connect(): the SDK sends hello after load, with the topics it has then. An app that binds after hello gets no theme from the hub.

An action is a request with exactly one handler, for example session.cost: “show the cost of this session”. The caller does not know which app handles it. The actions of the built-in tools are listed in The built-in tools.

<noun>.<verb or view>, lowercase: session.cost, project.plugins, project.memory. An app-specific name uses the app id as its prefix, for example cost.refresh. hub.* is reserved for the hub’s own actions. The hub handles hub.updates, with no params: it opens the update window, which updates the plugins in every config dir, and answers {ok: true, handledBy: 'hub'}. It handles hub.restart, with no params, the same way: it opens the app launcher on Restart Hub and restarts the hub process. With live terminals it waits there for a second Enter. The hub skips an app handler with a hub.* name, with a log line.

An app declares what it handles in its manifest (Manifest), because the hub needs it before the app runs:

"actions": {
"handles": {
"session.cost": { "params": { "session": "string?" }, "url": "?view=detail&session={session}", "mode": "message" }
}
}
Field Meaning
params Param names and types. The only types are string (required) and string? (optional)
url A path and query relative to the app origin, with no #. {name} is replaced by the param value. The hub skips an action whose url has a #
mode url (default) or message
Direction Type Payload
App → hub hub:invoke {id, action, params, open?}. id is a string that the caller picks, to match the result. open: 'pane' asks for the URL instead (see Routing)
Hub → app hub:result {id, ok: true, handledBy: <app id>, url?} or {id, ok: false, reason: 'unhandled' | 'bad-params'}
Hub → app hub:action {id, action, params}, to the handler in message mode
  1. Handler. The first enabled app in tab order that declares the action. When there is none, the hub answers unhandled.
  2. Params. The hub answers bad-params when a required param is missing, a param is not declared, or a value is not a string.
  3. Pane. With open: 'pane', when the action has a url and every param in its template is present, the hub fills it in as in step 6, on the handler’s origin and with no #t= fragment. It answers {ok: true, handledBy, url} with the absolute URL and does nothing else: no switch, no hub:action. The caller shows that URL in a frame of its own, where the page talks to the hub as a nested page (§5.1). Otherwise the hub goes on with step 4 and the result has no url.
  4. Switch. The hub switches to the handler’s tab.
  5. message mode. When the handler is live, the hub posts hub:action and answers hub:result at once. It does not wait for the handler to finish, and it does not queue a call for an app that is not live.
  6. url mode, and message mode when the handler is not live. When every param in the template is present, the hub fills it in with encodeURIComponent on each value and sets the iframe src. It builds the URL the same way as the first src, so the handler keeps what the hub adds, such as the #t= fragment. It refuses a result that is not on the handler’s origin. When a param is missing, or the handler has hub:closeGuard on, the hub only switches: setting src reloads the app.
  7. Handler duty. An app must handle every action that it declares with mode: "message". It logs an action it does not know.
  8. Availability. The caller shows a link or runs a key for an action only when the action is in welcome.actions. With no welcome, see No welcome.

A key press inside an iframe does not reach the hub page, so the app forwards the combos that the hub binds.

Direction Type Payload
App → hub hub:keydown {key, code, ctrl, alt, shift, meta}
Hub → app hub:keys {forward, keys}, as in welcome, after the user changes the hub’s keys. Sent to every app’s tab and nested page
  1. welcome.forward lists the combos by name. By default they are ctrl+alt+p, ctrl+alt+w, ctrl+alt+a, ctrl+,, ctrl+alt+ArrowLeft, ctrl+alt+ArrowRight and alt+1 to alt+N for the first nine tabs (ctrl+alt+1 to ctrl+alt+N on macOS, where Option+<digit> types a character). The user can change them in the hub’s shortcuts window or in config.json keys (Change the keys), but never to a combo in an app’s keys.keeps. An app takes the list from welcome, then from each hub:keys, not from this page. The SDK applies hub:keys and calls the page’s onKeys handlers, so a page that copied forwardCombos() sends the new list on.
  2. Combo name. The modifiers that are down, in the order ctrl, alt, shift, meta, joined by +, then the key. The key is e.key lowercased when that is a–z or 0–9. Else, when e.code is Digit<0-9>, it is that digit, so AZERTY’s & key is 1. Else, when e.key is not ASCII (a non-Latin layout, or macOS Option+<key>, which types another character), it is the key’s US character: the letter of Key<A-Z>, or , . ; ' ` / \ = - [ ] for Comma, Period, Semicolon, Quote, Backquote, Slash, Backslash, Equal, Minus, BracketLeft and BracketRight. So Cyrillic Ctrl+б on the Comma key is ctrl+,, while AZERTY’s , on the KeyM key stays ctrl+,. Else it is e.key as it is, except the space bar, which is Space. The e.code steps are skipped when getModifierState('AltGraph') is true: the browser sets it when AltGr, or Ctrl+Alt on a layout with AltGr, types a character. So Polish AltGr+A is ctrl+alt+ą, not ctrl+alt+a, and the character reaches the app.
  3. The app forwards a press only when its combo name is in the list, and then prevents its default action. Every other key stays in the app.
  4. The hub runs the binding for that combo.
  5. Help. welcome.keys maps each hub action to its combo, so an app’s help shows the keys the user set. The actions are hub.projectPicker, hub.configDirPicker, hub.appLauncher, hub.settings, hub.prevApp, hub.nextApp, hub.appByNumber, hub.reload (reload without the close prompt, ctrl+shift+r, shift+meta+r on macOS) and hub.voice (hold to talk, ctrl+shift+Space, bound only when config.json turns voice on). The combo of hub.appByNumber is a pattern, such as alt+{n}, where {n} is the tab number. The value is null when no key runs the action. A hub older than this field sends no keys, and the app shows its default keys. The SDK’s keyLabel(action) gives the keys in this system’s names.

An element that handles keys before the document sees them, such as a terminal, asks the SDK’s forwards(e) and lets a forwarded key through.

hub-app.json at the app root, next to package.json, tells the hub how to run the app and what it handles. An npm package must list it in files.

{
"manifest": 1,
"id": "cost",
"name": "Cost",
"icon": "dollar-sign",
"run": { "entry": "server.js", "defaultPort": 3543 },
"loading": { "verbs": ["Counting tokens…"] },
"actions": {
"handles": { "session.cost": { "params": { "session": "string?" }, "url": "?view=detail&session={session}", "mode": "message" } }
},
"publishes": [],
"provides": {}
}
Field Meaning
manifest The manifest format version. Now 1
id The app id
name, icon The tab name and a Lucide icon name
run.entry The server script, relative to the app root
run.defaultPort The first choice for the proxy port (Origin). Not a reservation
loading.verbs Lines for the hub’s loading screen while this app loads. Optional
actions.handles Actions
publishes The topics the app publishes (Events). Optional
provides Capabilities, for example {"projects": {"path": "/api/projects"}, "terminal": {"liveWork": "/api/terminals"}}. The hub finds a capability’s provider here
launcher.items The app’s own rows in the app launcher, for example "/api/hub/launcher-items" (rule 5). Optional
keys.keeps The combos the app keeps for its own commands, by combo name (Keys), for example ["ctrl+alt+n"]. The hub does not bind them. Optional
settings The user settings the app reads from the hub (Settings). Optional
  1. Discovery, not runtime. The manifest holds what the hub needs before the app runs. The protocol version comes from hello only, because the running document may be an older bundle.
  2. Where the hub reads it. For an apps entry with a path, the hub reads the manifest from that folder. For a built-in app, it reads it from the submodule, else from the installed package, and keeps no copy. The hub’s tests validate the manifest of each pinned package. See The apps entry and the launch.
  3. Skip. The hub skips an app, with a log line, when its file is missing or not valid JSON, manifest is a version it does not know, id does not match the id rule (Terms) or is not the app’s id, run.entry is not inside the app directory, a provides path or launcher.items does not start with /, a publishes topic breaks the topic rule or is the hub’s (Events), a keys.keeps entry is not a combo name with one modifier at least, or a settings entry is not valid (Settings). It skips one action, with a log line, when the action is not valid (Actions).
  4. Providers. For each capability, the first enabled app in tab order whose provides declares it is the provider. projects.path and terminal.liveWork must be paths on the provider’s origin. projects.path answers [{path, modifiedAt, worktrees?}], where worktrees lists the linked worktree paths folded into that repo row. terminal.liveWork answers {sessions: []}, and a pool whose provider has sessions is not evicted. With no provider, the capability is off: no terminal, and the project palette has no list.
  5. Launcher items. Each app with launcher.items gets its own rows; it is not a capability with one provider. The app launcher (Ctrl+Alt+A) fetches the path from the app’s origin each time it opens, with a 1 s timeout, and lists the rows under the app’s row. It answers {items: [{id, name, kind?, detail?, state?, path?, ops}]}. path is a file the row’s Ctrl+C copies, such as its config. ops lists the ops the row offers: restart (Ctrl+R) and remove (Ctrl+D, pressed twice). The hub sends an op as POST <items>/<id>/<op> and shows the message or error of the answer.

An event is a fact that any number of apps can receive. The hub publishes some topics itself, and an app publishes the topics its manifest lists.

Direction Type Payload
App → hub hub:hello subscribes: string[], the topics the app wants
App → hub hub:publish {topic, payload}, a topic in the app’s manifest publishes
Hub → app hub:event {topic, payload}
Topic From Sticky Payload
project.changed Hub Yes {project, encoded, name, worktrees}, or null when there is no project
theme.changed Hub Yes {theme, colorTheme, vars?}
App topics An app Yes See App topics
  1. A sticky topic keeps its last value in the hub. After welcome, the hub sends the last value of each sticky topic the app subscribes to, then every change. A topic that has had no value yet sends nothing.
  2. The hub sends an event only to live apps that subscribe to its topic.
  3. project is the absolute path and encoded is the hub’s encoded form of it: Claude Code’s project dir name, with every character that is not a letter or a digit changed to -. An app does not encode a path itself.
  4. worktrees is [{path, encoded}], the linked worktrees of the project’s repo that the projects provider reported. Claude Code keeps a worktree’s transcripts in its own project dir, so an app that reads transcripts by encoded reads each worktree’s encoded too. The array is empty for a path the user typed.
  5. The hub starts with no project, so that each app restores its own. It sends null only when the user clears the project. On null, the app clears its project scope.
  6. A document that the hub loaded from an action URL does not get the project.changed replay after welcome, so the link keeps its project. The next change goes to it as usual.
  7. An event never carries a secret.
  1. Names. <noun>.<verb>, lowercase, matching ^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)+$. project.changed, theme.changed and hub.* are the hub’s, and a manifest cannot list them.
  2. Declare. The hub drops a hub:publish whose topic is not in the sender’s manifest publishes. More than one app can publish the same topic.
  3. Payload. A plain object or null, at most 16 KB as JSON. Keep it small: ids and names, and let the receiver fetch the rest. The hub drops a payload that breaks this rule.
  4. Project. When the payload has a string project, the hub adds encoded and projectName to it, as in project.changed.
  5. Delivery. Every app topic is sticky, and its last value is cleared on a config-dir switch. The hub does not send an event back to the app that published it.
  6. Before welcome. The SDK keeps only the latest payload per topic and sends it on welcome. With no welcome, it drops them.
  7. Hidden apps. The hub sends an app topic only to the app on screen. A hidden app gets the last value of each topic it missed when it comes on screen, before hub:active. project.changed and theme.changed go to every app at once.

The topics, actions and capabilities of the built-in tools, such as Kanban’s session.changed, are not part of the protocol. See The built-in tools.

Pair What happens
App with no hello + v1 hub The hub sends the app no theme, project, keys or active state
v1 app + hub with no welcome The app gets no welcome. It forwards no keys, calls no hub action, and uses its own theme CSS
v1 app standalone The app serves the stub (SDK). It sends no message and uses its own URLs and themes

v0 (hub:project, hub:keys, hub → app hub:theme, hub:navigate, hub:keydown with {key} only) is not supported. An app and a hub from before v1 do not work with a v1 hub or app. So the v1 releases of the hub and all four apps are breaking and ship together, and the hub pins the exact v1 app versions.

  1. Wait. The app waits 2 s after hello for welcome. With none, its status is unanswered, and it removes the cached theme (Theme, rule 3). A welcome that comes later still applies.
  2. Calls wait too. An action call made before welcome and before the 2 s end waits for one of them. After the 2 s, can is false for every action and a call resolves unhandled.
Direction Type Payload Meaning
Hub → app hub:active {active: boolean} Whether this app is the tab on screen. Sent after welcome and on each tab switch. An app cannot find this itself: a hidden iframe is display: none, and visibilityState follows the top window
App → hub hub:closeGuard {on: boolean} While the app has it on, the hub does not reload it to route an action. Cleared when the app document loads again
App → hub hub:openExternal {url} The hub opens an http or https URL in a new window
App → hub hub:terminalToken {} The terminal provider asks for a fresh token
Hub → app hub:terminalToken {token} The answer. Sent only to the terminal provider

The hub gives the terminal provider its first token in the iframe URL fragment, #t=<token>.

Hub token. The hub never sends its token to an app. Cookies on localhost are shared across ports, so the browser sends the hub_token cookie to every app origin. The proxy removes hub_token from the Cookie header of each request and WebSocket upgrade before it forwards them.

A link with no target loads in the app’s frame, and most sites refuse framing. In the installed window, a target="_blank" link opens nothing. After welcome, the SDK opens links with openExternal:

  1. It listens for click and middle-button auxclick on window in the capture phase, so a handler that stops propagation does not hide the click. It runs before the page’s own click handlers, so a page cannot cancel it with preventDefault from such a handler.
  2. An http or https link goes to hub:openExternal, unless its origin is the page’s own origin or one in welcome.origins and it has no target="_blank". Those load in the frame. A link to the hub’s origin goes outside, because the hub page refuses framing.
  3. A link with another scheme, a download attribute or a named target (not starting with _) is left to the page, as is a click that an earlier capture listener prevented.
  4. Before welcome, and standalone, the SDK does not touch links.

An app lists its user settings in the manifest’s settings (Manifest has the entry rules). The hub stores the values, shows them in its settings modal (Ctrl+,) and sends them to the app. The app keeps no settings UI of its own for them.

Direction Type Payload Meaning
Hub → app hub:settings {settings: {[key]: boolean | string}} The app’s settings after the user changed one. Sent to the app’s tab and its nested pages
  1. Values. welcome.settings and hub:settings carry every key in the manifest, with the default for a key the user did not set. A saved value that the manifest no longer allows gives the default.
  2. Scope. One value per app for every config dir. The hub writes only a value that differs from the default, to settings of the app’s entry in config.json. A change applies at once, with no restart.
  3. Delivery. Only the app that lists the setting gets it. The hub sends hub:settings after each change the user saves.
  4. No hub. Standalone or with no welcome, the app uses its own defaults. The SDK’s settings is null then.

These are not in v1. Each is additive (Versioning).

  • A shared shortcut list: each app serves a shortcuts.json, named by a manifest field shortcuts, and the hub shows all of them in one overlay on Ctrl+Alt+K through the hub action hub.shortcuts.
  • More hub actions, such as app.<id> and hub.nextApp, with a user keymap that can bind app actions to global keys.
  • A providers map in the user config to pick one handler or provider among several. v1 takes the first enabled app in tab order.
  • The manifest fields invokes and reservedKeys.
  • Data events from an app server, sent over its IPC channel, such as a task that moved, so that an app hears them while its page is hidden.
  • hub.trace: a hub topic that mirrors every message the hub sends or receives, for tools such as an inspector.
  • A project param type that gives a template {project.encoded}.
  • run.ready in the manifest, and a fixed prefix for the ready line.
  • Added apps from npm packages, and external apps that the hub does not spawn.