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.

1. One-paragraph intro

OpenLoomi is your local-first AI coworker. It runs as a desktop app on your Mac, connects to the tools you authorise (Gmail, Slack, GitHub, Google Calendar, Notion, Linear, etc. via Composio, plus native bots for Telegram / WhatsApp / iMessage / Feishu / DingTalk / QQ / WeChat), watches the signals that come in, and surfaces daily decisions as cards on the desktop pet (Loomi the fox). You tap Approve and the action runs through the same connector — the result is written back into Memory so the next judgement is sharper. Nothing leaves your machine unless you opt in to a Connector.

2. Where things live (orientation)

3. The five-step first tour

After setup: ready, suggest this exact sequence. Each step is a single shell call plus a one-line description of what the user will see. Skip steps the user has already done — but always emit step 1 (health check) so the user knows what "still ready" looks like.

Optional extensions after step 4 (skip if the user is new):

• Custom Loop channel — register your own signal source (PUT /api/loop/channels with toolkit + toolSlug).
• Classifier rule — deterministic overrides for known signal patterns (PUT /api/loop/classifier-rules).
• Custom decision type — your own DecisionType icon + label (PUT /api/loop/types).

If the user asks for a hands-on walkthrough rather than just a recommendation, hand off to the openloomi-tour skill — it runs the same five steps with live probes and stops between each one for the user to react.

4. Quick reference card

End with this closed list so the user doesn't have to memorise URLs.

5. Hand-off

Finish with: "Run openloomi-tour from this Codex session for a guided walkthrough, or pick a number above and I'll run that step for you."

After api_not_ready

When the wizard times out waiting for the API, the recommended chat-side flow is:

1. Show the bridge's hints[] verbatim. Each is safe-to-print.
2. If canResume: true (always the case for api_not_ready), suggest the user simply re-runs the wizard. The state machine is idempotent — already-completed steps (e.g. install, env write) will be skipped immediately, and the wizard will land back inside wait_api.
3. If the user wants to raise the budget once, ship the pre-built resumeCommand (e.g. node <plugin>/scripts/loomi-bridge.mjs setup --yes --max-wait 180000) rather than asking them to invent the flag.

Follow-up commands

Sandbox notes

The setup wizard must be run outside the Codex sandbox (or with danger-full-access) — it needs to write to system application directories (/Applications on macOS, ~/.config/environment.d/ on Linux), launch a signed GUI helper, and reach the local HTTP API at http://localhost:3414. None of those survive read-only or default workspace-write mode in a fresh environment. If you are still inside a sandbox when the user asks for setup, request approval and re-run outside the sandbox before invoking the bridge. The bridge surfaces a sandbox-y reason in awaiting_user_action, launch_failed, or api_not_ready; the hints[] payload calls out the next concrete step (approve the request and retry).