---
name: openloomi-setup
description: "Run OpenLoomi one-time setup — auto-chains install → set Codex provider → launch → wait API → mint guest session token → ready in one call. Mirrors Claude's `/openloomi:setup`. Triggers: setup openloomi, install openloomi, install and run, 一键装好并跑起来, fix openloomi, finalize openloomi, install_required, awaiting_user_action, session_initialization_required, ai_provider_required, install_failed, api_not_ready, what now, what next, first time, what can i do."
allowed-tools: "Bash(node $SKILL_DIR/../../scripts/loomi-bridge.mjs 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:

   ```bash
   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.

| Flag                   | Default | Meaning                                                                                                                                                          |
| ---------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--yes`                | off     | Pre-approve install. Without it, the bridge stops at `INSTALL_CONFIRMATION_REQUIRED` because Codex can't presume consent. With it, the chain runs end-to-end.    |
| `--max-wait`           | 120000  | Global cap (ms) across the wait stages. Defaults to 120 s 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>` (and platform equivalents). Almost never actually hit; included for parity with the Claude side.                       |
| `--permission-timeout` | 60000   | Extra grace wait after `--api-timeout` when the desktop process is up but the API never woke up — only fires when the bridge can confirm the process is alive.   |
| `--bin-path`           | _auto_  | Explicit path to the OpenLoomi desktop bundle (e.g. `/Applications/OpenLoomi.app`). Mirrors Claude's flag and overrides the usual discovery order.                |

## 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.

| 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 `setup --yes` started.                                                                         |
| `effectiveBudgetMs` | number   | Total wait budget actually granted (api + permission grace).                                                         |
| `canResume`         | bool     | Always `true`. Re-running the wizard is the supported "keep waiting" action.                                         |
| `resumeCommand`     | string   | A pre-built 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 (informational).                                     |
| `steps`             | Step[]   | The existing audit trail.                                                                                            |
| `wait`              | object   | The raw `waitForApi` payload (code, elapsedMs, attempted, lastError, optional graceWait).                             |
| `status`            | object   | The latest `setup-status` snapshot.                                                                                  |

## Stop conditions and what they mean

| `setup`                        | When it fires                                                                                                                                                                                                                                                                                                |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ready`                        | All transitions completed. The desktop app is running, the API is reachable, the guest session token is minted, **and** the native Codex provider is the active agent. Surface `mode`, `version`, and `executionProviderSource` from `status`. |
| `awaiting_user_action`         | A transition that needs the user ran without a programmatic path. Most commonly: `nextAction: install_openloomi` because `--yes` wasn't passed, `nextAction: configure_ai_provider` because no provider is configured, `nextAction: open_openloomi` because the desktop process didn't wake, or `nextAction: inspect_codex_runtime` because the native Codex agent is not active. Walk the user through what they need to do and stop. |
| `install_attempted`            | (Informational.) The first `setup` invocation in a fresh environment must install before it can confirm READY. `--yes` already authorised the install; treat this as a normal await. |
| `install_failed`               | The platform install script exited non-zero (or hit `--install-timeout`). Show `install.code` / `install.message`.                                                                                                                                                                                            |
| `runtime_env_failed`           | The `set-codex-runtime-env` step failed (rare; usually a TCC prompt on macOS, or a write-permission error on Linux). Follow `runtimeEnv.message`.                                                                                                                                                            |
| `quit_for_env_reload_failed`   | The desktop app was running, the env var was written, but `quitDesktopApp` couldn't bring it down (TCC prompt blocking the kill). The only stop condition that **truly** needs the user to Quit+Reopen by hand. Surface `quit.message`.                                                                       |
| `launch_failed`                | `open -a <desktopMarker>` (or platform equivalent) returned a non-zero exit. On macOS this almost never happens for a signed .app; if it does, fall back to manual launch instructions.                                                                                                                       |
| `api_not_ready`                | The desktop app was launched but the local HTTP API didn't respond within `--api-timeout`. The bridge only adds `--permission-timeout` grace when it can confirm the desktop process is alive. `code` distinguishes network/slow (`API_NOT_READY`) vs TCC prompt (`PERMISSION_PROMPT_LIKELY`); `hints[]` and `resumeCommand` are pre-built; `canResume: true` makes re-running the wizard the recommended action. |
| `guest_login_failed`           | API is up but the one-tap guest login was rejected by `/api/auth/guest`. Show `session.code` / `session.error`. The user can sign in via the GUI and re-run setup.                                                                                                                                         |
| `step_limit_reached`           | Hit the internal step ceiling without reaching READY (default 8 transitions). Almost certainly a state-machine bug; show `steps[]`.                                                                                                                                                                          |

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 **open-source, local-first AI partner**, built to
> protect your attention. 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)

| Surface | Where |
| --- | --- |
| Desktop app | `/Applications/OpenLoomi.app` |
| Local HTTP API | `http://localhost:3414` (fallback `3515`) |
| Guest bearer token | `~/.openloomi/token` (base64-encoded JWT) |
| Codex runtime env | `OPENLOOMI_AGENT_PROVIDER=codex` (LaunchAgent, survives reboot) |
| Memory files | `~/.openloomi/data/memory/{people,projects,notes,strategy,chats,channels}/` |
| Knowledge Base | `GET /api/rag/documents` |
| Audit log | `GET /api/audit/...` |
| Pet widget | Watcher polls `~/.openloomi/loop/decisions.json` every 2s |

### 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.

| # | What | Command | What you'll see |
| --- | --- | --- | --- |
| 1 | **Health check** | `node "$PLUGIN/scripts/loomi-bridge.mjs" setup-status` | Same audit table you just got. Confirms Codex runtime is still the active default agent. |
| 2 | **Pet reacts** | `node "$PLUGIN/scripts/loomi-bridge.mjs" pet happy` | Loomi the fox flips to the happy sprite. Try `thinking`, `working`, `juggling` to see the rest of the 9-state set. |
| 3 | **Connect a tool** | Native: `node "$PLUGIN/skills/openloomi-connectors/scripts/openloomi-connectors.cjs" connect telegram` *or* OAuth: `composio link gmail` | A QR scan or browser OAuth opens; once you approve, the account shows in `list-accounts`. |
| 4 | **Run one Loop tick** | `TOKEN=$(cat ~/.openloomi/token \| base64 -d); curl -X POST http://localhost:3414/api/loop/tick -H "Authorization: Bearer $TOKEN"` | Loop pulls signals, classifies them, and enqueues decisions. Then `GET /api/loop/decisions?status=pending` to see the cards. Approve with `POST /api/loop/action/schedule`. |
| 5 | **Seed Memory** | `node "$PLUGIN/skills/openloomi-memory/scripts/openloomi-memory.cjs" add-memory "About me: ..." --file=tour/about-me.md` | A tour-owned `.md` shows up in `~/.openloomi/data/memory/tour/`. Future Loop ticks have grounding context without overwriting user memory. |

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.

| Want to… | Run |
| --- | --- |
| See health | `setup-status` |
| Flip the pet | `pet <state>` |
| Re-confirm Codex runtime | `codex-runtime-info` |
| List connectors | `openloomi-connectors list-accounts` |
| Search memory | `openloomi-memory search-all "<query>"` |
| Run a Loop tick | `POST /api/loop/tick` |
| See pending decisions | `GET /api/loop/decisions?status=pending` |
| Approve a decision | `POST /api/loop/action/schedule {decision_id, action:"run"}` |
| Archive old data | `archive` |

### 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

| Follow-up         | Bridge command                                          | When to suggest                                                                |
| ----------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------ |
| Status snapshot   | `setup-status`                                          | User asks "is everything wired up?" — read-only snapshot.                      |
| Pet state         | `pet happy` / `pet normal` / etc.                       | User asks about the Pet widget or wants to flip its state manually.            |
| Code runtime env  | `codex-runtime-info`                                    | User asks whether the desktop app is wired to Codex.                           |
| Install-only      | `install-openloomi --confirm`                           | User asks to install without launching (rare; mostly CI / VDI).                |

## 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).