/setup

description: Run OpenLoomi one-time setup — auto-chains install → launch → guest login → ready in one call
argument-hint: ""
allowed-tools: Bash(node ${CLAUDE_PLUGIN_ROOT}/scripts/loomi-bridge.mjs *)

/openloomi:setup

The bridge is now an **end-to-end** wizard. A single `setup` invocation walks the full state machine:

install OpenLoomi.app
  → launch the desktop app (`open -a <desktopMarker>`)
  → wait for the local HTTP API to come up
  → mint a guest bearer (one-tap sign-in)
  → { ready: true }

Each transition is automatic. **Do not** ask the user to click anything in the GUI. The bridge only surfaces a stop condition when the next step truly requires human action (e.g. no selected execution runtime is ready and no direct AI provider is configured — if Claude is selected, point the user at `claude auth login`; otherwise use OpenLoomi Desktop → API Settings).

Steps

1. If the install needs explicit consent (the bridge returns `setup: install_attempted` is the only case where this matters — normally `--yes` is passed straight through), confirm with the user before re-running. 2. Run: `node ${CLAUDE_PLUGIN_ROOT}/scripts/loomi-bridge.mjs setup --yes [--max-wait <ms>]` 3. Read the JSON. The bridge writes an audit trail of what it did into `steps[]`. Surface that to the user so they can see which transitions fired. 4. If `setup: ready` → done. 5. If `setup: awaiting_user_action` → the chain hit a step that genuinely needs the user (e.g. `nextAction: login_openloomi` but `canGuestLogin: false` because the local runtime didn't come up, or `nextAction: configure_ai_provider` because the runtime reports no ready selected execution provider and no per-user provider row). Explain what the user needs to do and stop.

Flags

| Flag | Default | Meaning | | ---------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--yes` | off | Pre-approve install (otherwise the bridge prompts y/N — but in Claude Code's Bash tool there is no TTY, so without `--yes` the install would silently cancel). | | `--max-wait` | 120000 | Global cap across all wait stages (in milliseconds). Defaults to 120s to absorb the first-run install + TCC prompts. | | `--api-timeout` | 120000 | Per-stage budget for "waiting for local API". Independent of `--max-wait`. | | `--install-timeout` | 300000 | Per-stage budget for "installing OpenLoomi". Covers download + copy on a 50 Mbps link. | | `--launch-timeout` | 10000 | Per-stage budget for `open -a <bundle>`. Almost never actually hit; included for symmetry. | | `--permission-timeout` | 60000 | Extra wait after `--api-timeout` if the desktop process is up but the API never woke up — typical macOS TCC/Accessibility prompt path. | | `--bin-path` | _auto_ | Override the discovered helper binary path (advanced). |

Live status

While the wizard is inside a long stage, the bridge writes a throttled 1 Hz line to **stderr** so the user can see progress:

  · installing OpenLoomi  (12s / max 5m) …
  · waiting for local API  (4s / max 2m) …
  · waiting on macOS permission prompt  (3s / max 1m) …

Stdout is reserved for the final JSON result — do not mix it.

`api_not_ready` payload

When `--api-timeout` elapses, the wizard returns an **actionable** JSON payload you can use to drive chat-side guidance. The original `setup: "api_not_ready"` shape is preserved for backwards compatibility; new fields are added alongside it.

| Field | Type | Meaning | | ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------- | | `ok` | bool | Always `false` for this stop condition. | | `setup` | string | Always `"api_not_ready"` here. | | `code` | string | Stable machine code: `"API_NOT_READY"` or `"PERMISSION_PROMPT_LIKELY"` (when desktop process is up but API is not). | | `stage` | string | Always `"wait_api"`. Reserved for future per-stage error codes. | | `elapsedMs` | number | Wall-clock time since `/openloomi:setup` started. | | `effectiveBudgetMs` | number | Total wait budget actually granted (api + permission grace if it kicked in). | | `canResume` | bool | Always `true`. Re-running the slash command is the supported "keep waiting" action. | | `resumeCommand` | string | A pre-built slash command the user can paste — already uses a sensible raised `--max-wait`. | | `hints` | string[] | 1–3 hints, safe to print verbatim. Includes the macOS TCC prompt hint on Darwin. | | `overCap` | bool | `true` if the elapsed time exceeded the global `--max-wait` cap (informationa