Openloomi Setup

OpenLoomi Setup (end-to-end wizard)

The bridge now exposes a single end-to-end wizard: setup --yes. One invocation walks the full Codex state machine:

install OpenLoomi.app from the official GitHub release
  → set OPENLOOMI_AGENT_PROVIDER=codex in the GUI launchd / environment.d
     (auto-restarts the desktop if it was already running)
  → launch the desktop app (`open -a <desktopMarker>` / platform equivalent)
  → wait for the local HTTP API to come up on http://localhost:3414
  → mint a guest bearer (one-tap sign-in) into ~/.openloomi/token
  → { 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. AI provider not configured, or the native Codex runtime isn't reachable.

This wizard is the Codex-side equivalent of Claude's /openloomi:setup. Both plugins speak the same bridge commands, the same flag names, and the same stop-condition vocabulary so an install step that works on one works on the other.

Quick workflow

1. Make sure the Codex sandbox is set to a mode that allows the wizard to actually run. setup needs to write to /Applications (macOS) or ~/.config/environment.d/ (Linux), install/launch the desktop helper, and reach http://localhost:3414. workspace-write is the minimum that usually works; danger-full-access is the safe choice for the first run. If you do not have approval, ask the user before invoking the bridge.

2. If the bridge returns setup: install_attempted (only happens on the very first invocation when --yes is required), this is informational — --yes is already passed through and the wizard proceeds.

3. Run:

   node "$SKILL_DIR/../../scripts/loomi-bridge.mjs" setup --yes [--max-wait <ms>] [--api-timeout <ms>] [--install-timeout <ms>] [--launch-timeout <ms>] [--permission-timeout <ms>] [--bin-path <path>]

4. 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 (status_check → install → runtime_env_write → quit_for_env_reload (only when needed) → launch → wait_api → guest_login).

5. If setup: ready → done.

6. If setup: awaiting_user_action → the chain hit a step that genuinely needs the user (e.g. nextAction: install_openloomi because --yes wasn't passed, nextAction: configure_ai_provider because no AI provider is configured, or nextAction: open_openloomi because the desktop process won't auto-launch). Explain what the user needs to do and stop — do not auto-retry.

7. If setup: api_not_ready → show the bridge's hints[] and the pre-built resumeCommand. Re-running the wizard is always safe; the state machine is idempotent. Re-approval may be needed to leave the sandbox.

Flags

All flags are also accepted by the bridge directly. Names + defaults are identical to Claude's /openloomi:setup so the two plugins speak the same dial language.

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 (+ --permission-timeout grace) 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.

Stop conditions and what they mean

The bridge's stdout output is authoritative. Never invoke the platform install script (setup.{macos,linux,windows}.*) directly — only the bridge may run it, and only after explicit user consent (which is what --yes records).

Codex provider wiring

Before any launch, the bridge writes OPENLOOMI_AGENT_PROVIDER=codex so the freshly-started desktop server picks up the Codex runtime. On macOS this is done via launchctl setenv plus a LaunchAgent so the variable survives reboot; on Linux the bridge edits ~/.config/environment.d/; on Windows the user must set the variable manually. codex-runtime-info always reports the current effective value.

Post-ready walkthrough

When setup: ready fires, the wizard is done. Print the canonical post-setup hand-off so the user knows what they just installed and what to try next. The bridge JSON above is for machines; this section is the human-facing surface and supersedes the earlier "do not improvise" rule with a richer, scripted intro + tour. Print all four parts on the very first setup: ready emission. On later re-runs you may abbreviate to the audit table plus "where to go next" line, but never skip the intro.