OpenLoomi Claude Plugin Skill

This skill is the single entry point for the OpenLoomi ↔ Claude Code integration. It is intentionally thin: it delegates to loomi-bridge.mjs for every side effect and never duplicates OpenLoomi business logic, connector implementations, or memory storage.

When to call loomi-bridge

Call loomi-bridge.mjs whenever ANY of the following is true:

• User says openloomi, loomi, pet, /openloomi:*, or asks about "the local AI assistant".
• User wants to install, configure, verify, or update OpenLoomi.
• User asks Claude Code to query their memory, look up a previous conversation, or "search my notes".
• User wants to set the Loomi Pet to a specific state.
• User wants today's LLM cost / usage.
• User asks about hooking Claude Code up to "the pet" or "loop".

When the user just wants something Claude can do natively (write a file, answer a question, etc.) and OpenLoomi is not mentioned, do not invoke the bridge.

Bridge subcommands (quick reference)

All subcommands emit JSON to stdout unless noted otherwise. All failure modes emit JSON (never bare stack traces).

Secrets contract (verbatim from plugins/codex/README.md §256–296)

Claude Code must never receive or print:

• model provider API keys (the plugin never reads them — the runtime handles its own AI provider configuration);
• OAuth access tokens or refresh tokens;
• connector app secrets;
• OpenLoomi auth tokens;
• local secure-storage contents (e.g. ~/.openloomi/token contents).

Allowed status-only checks:

OPENLOOMI_AUTH_TOKEN present/missing
~/.openloomi/token present/missing
native Claude CLI authenticated / not authenticated
AI provider configured/missing
connector configured/missing
local API reachable/unreachable

The bridge may report key names and presence. It must not print values. AI provider readiness comes entirely from the OpenLoomi runtime's /api/preferences/ai response (nativeRuntime / aiProviderConfigured).

Discovery chain

The bridge resolves your local OpenLoomi runtime in this order:

1. OPENLOOMI_BIN
2. OPENLOOMI_HOME / OPENLOOMI_INSTALL_DIR
3. OPENLOOMI_REPO_DIR
4. PATH lookup
5. Platform defaults — the desktop app's main binary:
   • macOS: ~/Applications/OpenLoomi.app/Contents/MacOS/openloomi
   • Linux: /opt/openloomi/openloomi (or ~/.local/bin/openloomi, /usr/local/bin/openloomi)
   • Windows: %LOCALAPPDATA%\OpenLoomi\openloomi.exe
6. ${CLAUDE_PLUGIN_DATA}/config.json (non-secret cached install path)
7. --bin-path <p> explicit flag
8. Otherwise: emit nextAction: install_openloomi

Hook events → Pet states

idle, sleeping, sweeping, presenting are managed by the loop watcher and are not set by hooks.

Reminders for Claude

• Never handle AI provider keys in this plugin. AI provider configuration lives in the OpenLoomi runtime; the runtime detects the user's local claude CLI auth on its own. If the user reports missing Claude CLI auth, point them at claude auth login or at OpenLoomi Desktop → API Settings for a custom endpoint.
• Never auto-install hooks. Always require an explicit /openloomi:hooks install.
• Always exit 0 on Stop. Archive failures are reported via stdout JSON with _openloomi.archive: "skipped", reason: ....
• When unsure, default to running loomi-bridge setup-status --json and respond based on the structured output — don't guess.