Helix Fleet

Orchestrator cloud context (check before setup)

If HELIX_ORCHESTRATOR_RUN_ID or HELIX_SKILL_CREDENTIAL_FILE is set, this skill runs in Helix Console. This section takes precedence over local setup and browser instructions below.

• First call the plugin's bin/helix orchestrator-protocol (Windows: bin/helix.cmd orchestrator-protocol). It must print 1. Otherwise stop with an actionable request to update the Helix plugin/CLI; never run an older binary's setup commands.
• Use the normal helix <surface> up, push, state, and wait commands. The CLI selects cloud transport and the assigned project automatically. Keep the same slug within this task.
• Do not start local servers or Fleet, open a browser, curl localhost, use --local, log in, or change profiles/projects. Do not read or print the credential file. Do not remove the injected environment variables.
• up returns the Console session URL. Use that URL wherever the local instructions request Board/Fleet links. Events go to Console; human responses and gate approvals still come from the person through the normal wait protocol.
• On cloud or compatibility errors, report the error. Never fall back to local mode. Outside this context, follow the local behavior below unchanged.

Mission control. Fleet is a global singleton (port 4890). Every session up (spark, canvas, loop, arena, swarm, stream, archive) starts it when it is down and returns fleet: {url, started}, so the board is there whenever a session is; servers register with it on start, push their needs-you items on change, and Fleet health-pings them for liveness. Agents never push to Fleet — the only agent verbs are up and status.

CLI

# start/reuse THE fleet server (port 4890), open the board
${CLAUDE_PLUGIN_ROOT}/bin/helix fleet up [--no-open]

# registry as JSON: {sessions:[...], attentionTotal}
${CLAUDE_PLUGIN_ROOT}/bin/helix fleet status

On Windows, ${CLAUDE_PLUGIN_ROOT}\bin\helix.cmd in place of bin/helix; the rest of the command is the same.

• up opens the browser itself, from inside the binary. --no-open is for headless or scripted runs — never a way around a permission prompt. If a prompt is declined, hand the user ! open <url> and carry on.
• Data: ~/.helix/fleet/ (registry.json + fleet.db). Port override: HELIX_FLEET_PORT env (must match in Fleet AND the app servers).
• status is the scriptable view — use it to answer "what's running / what needs the user" without opening anything. Session fields: app, slug, projectDir, port, alive, title, attention:[{id,kind,label,since}], viewers, startedAt.
• Stale-server rule as siblings: up restarts an outdated fleet server on the same port.

What the board shows (so you can point the user at it)

• needs you queue (left): every unanswered question/decision, open gate, and unratified bar across all sessions, newest first — click jumps into the session.
• Session rows grouped by project: attention badge, app chip, slug, title, live/dead, uptime, viewers. Click a row → the session opens as an embedded tab inside Fleet; ⧉ opens its native tab; ✕ prunes dead rows.

The agent's obligations (this is the whole "integration")

1. Sessions register themselves — you do nothing to appear on the board.
2. Keep your session's title honest — Fleet displays it:
   • canvas → your latest status pill text
   • stream → your status tile text
   • loop → the loop.init name Stale status = a lying Fleet row.
3. A session up starts Fleet if needed, so rows rarely go missing. If the user says one is, rerun that app's up (same slug/port; open tabs reconnect) — it re-registers.

When the user asks "what needs me?"

Run ${CLAUDE_PLUGIN_ROOT}/bin/helix fleet status, and summarize the attention items grouped by session — don't make them open the board if a sentence answers it.