# Openloomi

> OpenLoomi runtime integration for Claude Code. Use when the user mentions OpenLoomi, wants to install/configure it, query their local memory via the Loomi runtime, change the Loomi Pet state, view LLM usage, run a one-shot task through the local runtime, or install the optional hooks that mirror Claude Code's lifecycle onto the Loomi Pet and auto-archive every Stop into OpenLoomi memory. Triggers: openloomi, loomi, /openloomi:*, local memory, RAG search, insights, loop, pet state, openloomi tour, guided tour, walk me through openloomi, show me everything, 一条龙, 体验一下, 带我看一下.

- Skill: `melandlabs/openloomi-2` (Agent Skill)
- Install (CLI): `npx skillmds@latest add melandlabs/openloomi-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/melandlabs/openloomi-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: melandlabs (https://skillmd.com/u/melandlabs)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/melandlabs/openloomi-2

---


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

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