openloomi-setup

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:

   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 . The bridge only adds grace when it can confirm the desktop process is alive. distinguishes network/slow () vs TCC prompt (); and are pre-built; makes re-running the wizard the recommended action.

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)

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=people/me.md	A real .md shows up in ~/.openloomi/data/memory/people/. Future Loop ticks have grounding context.

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