openloomi-tour

Files (1)

• SKILL.md

SKILL.md (first lines)

# OpenLoomi Tour — Hands-on Walkthrough

This skill is the **canonical first-run experience** for Claude Code
users. After `/openloomi:setup` finishes and prints its post-ready
walkthrough, the user can type **`/openloomi:tour`** (or any of the
trigger phrases) and you'll run the same pipeline live, stopping
between phases so the user can react.

The tour is **interactive, idempotent, and skippable**. Each phase
checks its own prerequisite and lets the user move on with `next` /
`skip` / `back`. Nothing is destructive — if the user already did a
phase, you re-confirm it and move on.

---


## Reference docs

Quick links to the OpenLoomi docs that this tour draws from. Every
phase below cites the relevant entries inline.

| Topic | Doc |
| --- | --- |
| Getting started / install / one-time setup | <https://openloomi.ai/docs/getting-started> |
| What OpenLoomi is (the pipeline in one page) | <https://openloomi.ai/docs/what-is-openloomi> |
| Glossary — every term used here (Connector / Signal / Loop channel / Action Runner / etc.) | <https://openloomi.ai/docs/glossary> |
| Loop engine — ticks, Decisions, cards, channels, classifier rules | <https://openloomi.ai/docs/loop> |
| Loop — Approve / Edit Draft / dry-run anatomy of a Card | <https://openloomi.ai/docs/loop#approvals-and-dry-run> |
| Memory — people / projects / notes / insights / Screen Capture | <https://openloomi.ai/docs/memory> |
| Knowledge Base / Library — uploaded documents (PDF, DOCX, MD, …) | <https://openloomi.ai/docs/library> |
| Connectors — Slack / Gmail / GitHub / Linear / Notion / HubSpot / … | <https://openloomi.ai/docs/connectors> |
| Native messaging bots — Telegram / WhatsApp / iMessage / Feishu / DingTalk / QQ / WeChat | <https://openloomi.ai/docs/messaging-apps> |
| Composio / Loop channel — OAuth broker for 1000+ apps | <https://openloomi.ai/docs/glossary#composio--loop-channel> |
| Attention Agent — Loomi the fox, card bubbles, sprite states | <https://openloomi.ai/docs/attention-agent> |
| Agent Runtimes — Claude / Codex / OpenCode / Hermes / OpenClaw | <https://openloomi.ai/docs/reference/agent-runtimes> |
| Plugins — bridge from Claude Code / Codex into OpenLoomi | <https://openloomi.ai/docs/plugins> |
| Automation / Proactive Tasks — recurring scheduled work | <https://openloomi.ai/docs/automation> |
| Chat — conversational entry point (not Loop) | <https://openloomi.ai/docs/chat> |
| Skills — reusable capabilities inside OpenLoomi | <https://openloomi.ai/docs/skills> |
| Audit Log — every consequential moment recorded | <https://openloomi.ai/docs/privacy-security#audit-logs> |
| Privacy & Security — local-first, AES-256, what's stored where | <https://openloomi.ai/docs/privacy-security> |
| Changelog — what's new in each release | <https://openloomi.ai/docs/changelog> |

## Phase 0 — Pre-flight

Before running any phase, do **three** things in this exact order:

```bash
# 1. Readiness (sandbox-aware)
node "${CLAUDE_PLUGIN_ROOT}/scripts/loomi-bridge.mjs" setup-status --json

# 2. If loopbackAccessAmbiguous: true, refresh host probe outside sandbox
node "${CLAUDE_PLUGIN_ROOT}/scripts/loomi-bridge.mjs" run-host-probe

# 3. Confirm the selected execution provider. Only inspect Claude auth when
#    Claude is selected; Codex/OpenCode/Hermes/OpenClaw use their own auth.
node "${CLAUDE_PLUGIN_ROOT}/scripts/loomi-bridge.mjs" setup-status --json | jq '{executionProviderReady, executionProviderSource, nativeRuntimeProvider, nativeRuntime}'
```

Decision tree:

| Pre-flight outcome | Tour action |
| --- | --- |
| `ready: true`, `executionProviderReady: true` | Proceed straight to Phase 1, regardless of which runtime is selected |
| `ready: false`, `nextAction: setup` (or no setup) | Tell the user setup hasn't run yet. Offer to invoke `/openloomi:setup` first, then return to tour |
| `ready: false`, `OPENLOOMI_API_UNREACHABLE` | Re-run `run-host-probe` outside the sandbox; if still unreachable, surface the bridge's `hints[]` and stop |
| `nativeRuntimeProvider: "claude"`, `nativeRuntime.authenticated: false` | Point user at `claude auth login`, then re-run setup-status. The tour can continue but Loop won't have a runtime to drive actions |
| Non-Claude `nativeRuntimeProvider`, `executionProviderReady: true` | Proceed without asking for Claude login or an Anthropic API key; the selected runtime brings its own auth |

Print the user's current state in one line (mode, installed, selected
execution provider, provider ready) before announcing Phase 1.

---

## Phase 1 — Pet reaction (always run)

The pet is the **fastest, cheapest, safest** proof that the desktop is
listening. Run four "sight" states in sequence so the user sees the
sprite set:

```bash
node "${CLAUDE_PLUGIN_ROOT}/scripts/loomi-bridge.mjs" pet happy
node "${CLAUDE_PLUGIN_ROOT}/scripts/loomi-bridge.mjs" pet thinking
node "${CLAUDE_PLUGIN_ROOT}/scripts/loomi-bridge.mjs" pet working
node "${CLAUDE_PLUGIN_ROOT}/scripts/loomi-bridge.mjs" pet juggling
```

After each, say "Loomi just showed the `<state>` sprite — that proves
the desktop is watching the pet watcher and accepting state changes
from Claude Code." End by leaving the pet at `happy` (success-state
feel).

For the full state taxonomy, see the [Attention Agent](https://openloomi.ai/docs/attention-agent) doc; for the broader pipeline see the [Glossary](https://openloomi.ai/docs/glossary).

If `POST /api/pet/state` returns "would have set state to X — pending
OpenLoomi endpoint", note that the runtime is older than the bridge
expects; the pet widget will catch up via the `~/.openloomi/loop/`
file watcher anyway. Avoid `sleeping` / `sweeping` — those are
watcher-only on the API surface and the bridge will surface a 400
`invalid_state`.

---

## Phase 2 — Onboarding & input sources (interactive)

This is the first **real** action and the first place the user may have
to do something in another window. There are **three** input paths;
offer them all and let the user pick:

> **A. Native bot** ([Telegram / WhatsApp / iMessage / Feishu / DingTalk
> / QQ / WeChat](https://openloomi.ai/docs/messaging-apps)) — fastest, no browser OAuth. Best if you already use
> one of those.
>
> **B. [Composio OAuth](https://openloomi.ai/docs/glossary#composio--loop-channel)** (Gmail / Slack / GitHub / Google Calendar /
> Notion / Linear / HubSpot / LinkedIn / Jira / Asana / Discord / X) —
> one browser click, works for the apps most people already have. Full list at [Connectors](https://openloomi.ai/docs/connectors).
>
> **C. [Screen memory](https://openloomi.ai/docs/memory) (macOS only)** — right-click the Loomi pet on the
> desktop → **Open Settings** → enable **Screen Capture**. The global

From melandlabs/openloomi, Apache-2.0.

More from melandlabs/openloomi