OpenLoomi Pet Sub-skill (Codex)

Codex parity note: this skill ships only in the Claude plugin today. The Codex plugin's loomi-bridge.mjs already exposes the same pet <state> command and lifecycle hooks (see plugins/codex/README.md § Codex Pet lifecycle hooks), and the file-based theme system is runtime-side, identical across both plugins. The Codex plugin does not yet have its own openloomi-pet SKILL.md — this stub mirrors the Claude one so users on either surface get the same guidance.

When Codex's pet <state> behaviour diverges from Claude's, this file is the authoritative Codex-side reference.

The Loomi Pet has 9 universal state names. The runtime's map_state_to_pet watcher renders the matching sprite for whichever theme is active (fox, capybara, or any folder under ~/.openloomi/pet-custom/). State set:

Available commands

• node ${CODEX_PLUGIN_ROOT}/scripts/loomi-bridge.mjs pet <state> — synchronous, returns JSON; use only when the user explicitly asks.
• Hooks call state <name> --event <event> automatically (fire-and-forget, 2s timeout).

The Codex bridge mirrors the Claude bridge's cmdPet. Invalid state names are rejected client-side before any HTTP call. The endpoint POST /api/pet/state may not exist in the target runtime; the bridge falls back to a polite "endpoint pending" notice without raising an error.

node plugins/codex/scripts/loomi-bridge.mjs pet happy
node plugins/codex/scripts/loomi-bridge.mjs pet working

Failure modes (all return structured JSON, never throw):

Help the user customize their pet's appearance

The Codex bridge only drives the state — sprite overrides and theme folders are file-based and live outside the plugin. When the user asks to "change the pet's look" or "add a custom character", walk them through the file system. Do not try to write pet-config.json from the bridge; the bridge has no such command and the runtime's file watcher does the work.

Decision tree

1. "I just want the other built-in" → right-click Loomi → Theme → Fox / Theme → Capybara. Persisted in ~/.openloomi/pet-config.json under activeTheme. Long-press (~600 ms) is the fallback if contextmenu is swallowed by the host.
2. "I want my own character" → drop a folder at ~/.openloomi/pet-custom/<name>/ with PNGs named after the states. The watcher auto-discovers it within ~250 ms and the theme appears in the menu.
3. "I want to change just one sprite" → edit ~/.openloomi/pet-config.json's overrides map. Wins over both built-ins and custom-theme sprites for the matching (theme, state) pair.
4. "I want to make my theme the default" → set activeTheme to the custom theme's folder name.

What the bridge can and can't do

Filename conventions to communicate

When guiding the user through a custom theme, surface these conventions up-front:

• PNG only. .gif, .webp, .apng, .lottie are silently ignored.
• Bare or prefixed names both work. idle.png, loomi-idle.png, capybara-thinking.png, my-pack-sweeping.png all normalize correctly (case-insensitive).
• One recognizable state PNG is enough. The folder is registered as a theme as soon as it has ≥1 normalized state stem; missing states fall through to the active theme's idle sprite.
• Hidden / dot-prefixed folders are ignored. .git, .DS_Store etc.

Override JSON shape to communicate

The overrides map is camelCase on the wire — activeTheme, customThemesDir. Snake_case keys silently no-op the assignment (the unit test at apps/web/src-tauri/src/pet/theme.rs:499 pins the contract). Use the exact shape:

{
  "version": 1,
  "activeTheme": "fox",
  "customThemesDir": "~/.openloomi/pet-custom",
  "overrides": {
    "fox": {
      "idle": "/absolute/path/to/my-fox-idle.png"
    }
  }
}

Absolute paths only — the runtime routes them through tauri::convertFileSrc, so relative paths and ~/ prefixes will not resolve.

Common pitfalls to surface

• The folder doesn't show up — usually a missing or mis-named state PNG. Run them through the filename convention table.
• Override doesn't apply — host log line [loomi-pet/theme] failed to parse ~/.openloomi/pet-config.json means the JSON itself is malformed and defaults loaded. Host log line [loomi-pet/theme] failed to read <path>: <io error> means the path doesn't resolve.
• Theme menu tick is wrong / stuck — almost always a camelCase vs snake_case wire-format mismatch. The widget reads activeTheme, not active_theme.
• sleeping / sweeping rejected by /api/pet/state — those are watcher-only vocabulary; the runtime returns 400 invalid_state. The Codex bridge surfaces this as PET_FAILED (not INVALID_STATE) — distinguish it from a typo before reporting.

Codex-specific deltas vs the Claude plugin

What NOT to do from Codex

• Do not try to call POST /api/pet/state with sleeping or sweeping. The API rejects them; the watcher owns them.
• Do not try to write pet-config.json from the bridge. The bridge has no command for it; the file watcher owns updates.
• Do not invent new state names. CAPYBARA_STATES rejects them before any HTTP call.
• Do not claim support for non-PNG sprite formats. The asset pipeline is static PNG only.
• Do not say "I'll set up your custom theme for you" if you can only walk them through the file system. The watcher does the work; you guide.

See also

• Customize your Loomi Pet (user docs) — full guide to themes, custom folders, overrides, troubleshooting
• Pet API — POST /api/pet/state for external tools
• Attention Agent — the desktop pet as a whole
• The runtime source: apps/web/src-tauri/src/pet/theme.rs (custom themes + overrides), apps/web/src-tauri/src/pet/watcher.rs::map_state_to_pet (state resolution)
• Claude-side counterpart: plugins/claude/skills/openloomi-pet/SKILL.md