# Openloomi Pet

OpenLoomi Pet sprite & state helper for Claude Code.

- Repository: https://github.com/melandlabs/openloomi (1038 stars)
- Category: AI and agents
- License: Apache-2.0
- Last updated: 2026-09-24
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add melandlabs/openloomi --skill openloomi-pet -g -a claude-code -y`
Codex: `npx skills add melandlabs/openloomi --skill openloomi-pet -g -a codex -y`
Cursor: `npx skills add melandlabs/openloomi --skill openloomi-pet -g -a cursor -y`
Gemini CLI: `npx skills add melandlabs/openloomi --skill openloomi-pet -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add melandlabs/openloomi`

## Description

OpenLoomi Pet sprite & state helper for Claude Code. Use when the user wants to change their Loomi Pet state, switch theme, drop in a custom character, override individual sprites, or ask Claude to mirror its lifecycle onto the pet. Triggers: pet state, /openloomi:pet, set pet, loomi pet, pet to happy, pet to working, pet to thinking, fox sprite, capybara sprite, custom pet theme, pet-custom, pet-config, override pet sprite.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# OpenLoomi Pet Sub-skill

The Loomi Pet has 9 universal state names. The plugin ships the fox
(`loomi-*`) sprite set for branding; the OpenLoomi runtime's
state-resolution watcher renders the matching sprite for whichever
theme you have active (fox or capybara, or any folder under
`~/.openloomi/pet-custom/`). State set:

| State | When to use |
|---|---|
| `happy` | A task just completed successfully |
| `idle` | Loomi is waiting for the next loop tick (watcher-only, do not set from Claude) |
| `juggling` | Multiple sub-agents are running |
| `needsinput` | Permission prompt / elicitation dialog visible |
| `presenting` | Fresh decision requires the user's review (watcher-only, do not set from Claude) |
| `sleeping` | Local hour outside 6, 22 with no pending work (watcher-only, do not set from Claude) |
| `sweeping` | User dismissed a card just now (watcher-only) |
| `thinking` | Between steps, awaiting LLM response |
| `working` | A tool call is in progress (`PreToolUse` hook fires this) |

## Available commands

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

Sprite set is hardcoded in the bridge, invalid state names are rejected
before any HTTP call. The endpoint `POST /api/pet/state` may not yet exist
in the target OpenLoomi runtime; the bridge falls back to "would have set
state to X, pending OpenLoomi endpoint" without raising an error.

---

## Help the user customize their pet's appearance

The 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

The rest: https://github.com/melandlabs/openloomi/blob/HEAD/plugins/claude/skills/openloomi-pet/SKILL.md