openloomi

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)

Subcommand	Slash command	Typical use
setup	/openloomi:setup	First-run install + status
setup-status [--json]	/openloomi:status	Stable JSON status
install [--yes]	(internal)	User-approved install
login	(internal)	Open OpenLoomi login surface, report status
pet <state>	/openloomi:pet	Set Pet state (9 universal states; theme-agnostic)
state <name>	(internal/hook)	Fire-and-forget Pet state from hook
archive	(internal/hook)	Archive last transcript on Stop
usage	/openloomi:usage	Today's LLM usage summary
install-hooks	/openloomi:hooks install	Merge hooks into ~/.claude/settings.json
uninstall-hooks	/openloomi:hooks uninstall	Strip only the plugin's hook block
hooks-status	/openloomi:hooks status	Report hook merge state
loop (doorway)	/openloomi:loop	Loop dashboard snapshot — delegates to the openloomi-loop sub-skill
memory <query> (doorway)	/openloomi:memory	Search memory + KB + insights — delegates to the openloomi-memory sub-skill
version	(internal)	Print plugin version

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

Claude Code hook	Pet state
SessionStart	greet (fallback presenting if capybara theme active)
UserPromptSubmit	thinking
PreToolUse (Bash|Edit|Write|Read|Grep|Glob)	working
PostToolUse	thinking
Stop	archive → happy
SubagentStart	juggling
SubagentStop	thinking
Notification (permission_prompt|elicitation)	needsinput

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.