Pets

Pets come from the public petdex gallery.

Pets are purely cosmetic. They have no effect on prompt caching, tokens, or the agent's behavior — the sprite is a display concern only. The feature is off by default and stays dormant until you install and select a pet.

How it works

• Pets are installed into your profile's pets/ directory (<NEDURA_HOME>/pets/<slug>/), so each profile keeps its own set.

• Selecting a pet writes display.pet.slug and display.pet.enabled to config.yaml — nothing is stored as a secret or env var.

• Each surface watches the activity it already tracks and maps it to one of six animation states. The mapping lives in one place so every surface behaves the same:

  Agent activity	Pet state
  A tool/turn just failed	failed
  A plan finished (all todos done)	jump (celebrate)
  A turn finished cleanly	wave
  A tool is executing	run
  The model is thinking/reading	review
  Turn in flight (unspecified)	run
  Blocked on you (a clarify/approval prompt is open)	waiting (falls back to idle on legacy 8-row sheets)
  Nothing happening	idle

Rendering

In the terminal (CLI/TUI), Nedura renders the sprite at full fidelity when your terminal supports a graphics protocol (kitty, Ghostty, WezTerm, iTerm2, or sixel). Otherwise it falls back automatically to a truecolor Unicode half-block rendering. Inside a pipe or redirect (no TTY), terminal rendering is disabled by design.

Quick start (CLI)

# Browse the gallery (filter by substring)
nedura pets list
nedura pets list cat

# Install a pet and make it active in one step
nedura pets install boba --select

# Preview / animate it in your terminal (Ctrl+C to stop)
nedura pets show

# Check your setup
nedura pets doctor

nedura pets commands

Goal	Command
Browse the gallery	nedura pets list [query] [--limit N]
List installed pets	nedura pets list --installed
Install a pet	nedura pets install <slug> [--select] [--force]
Set the active pet	nedura pets select [slug] (omit slug for a picker)
Resize the pet everywhere	nedura pets scale <factor> (e.g. 0.5, clamped 0.1–3.0)
Preview/animate	nedura pets show [slug] [--state <s>] [--cycle] [--once] [--mode <m>] [--scale <f>]
Disable the pet	nedura pets off
Remove an installed pet	nedura pets remove <slug>
Diagnose setup	nedura pets doctor

nedura pets show flags:

• --state — play a single state (idle, wave, run, failed, review, jump).
• --cycle — cycle through every state.
• --once — play once instead of looping.
• --mode — override the render protocol (kitty, iterm, sixel, unicode, auto).
• --scale — override the on-screen scale (0 = use config).

/pet slash command

Inside the CLI and TUI you can manage the pet without leaving the session:

• /pet — toggle the pet on/off (adopts the first installed pet if none is active).
• /pet list — browse the gallery.
• /pet scale <factor> — resize the pet everywhere (e.g. /pet scale 0.5).
• /pet <slug> — adopt a specific pet.
• /pet off — disable the pet.

Generating a pet (/hatch)

Beyond installing pre-made pets from the gallery, Nedura can generate a brand-new pet from a text description — its own AI sprite-generation pipeline.

• CLI/TUI: /hatch <description> (alias /generate-pet), or nedura pets → the generate flow.

How generation works (a two-step, cost-bounded flow):

1. Base drafts — a handful of cheap, prompt-only "what should this pet look like" variants are generated. You pick one, or remix/retry for a fresh round.
2. Hatch — the chosen base is used as a reference image to generate one grounded animation row per Nedura state (idle, thinking, tool use, etc.), which are deterministically sliced into frames and packed into a standard petdex/Codex atlas (8×9 grid of 192×208 cells). The result is a valid spritesheet you keep — and could petdex submit.

Image backend

Generation uses the active image-generation provider, but it requires reference-image grounding so each animation row stays the same character as the base. Reference-capable backends: Nous Portal, OpenRouter, OpenAI (gpt-image-2), and Krea. OpenRouter/Nous Portal run a quality-first model chain by default.

• Resolution order prefers Nous Portal → OpenAI → OpenRouter.
• If no reference-capable backend is configured, generation surfaces an actionable error pointing you to nedura tools → Image Generation. (Installing/adopting existing gallery pets needs no image backend.)
• Override the backend with the NEDURA_PET_IMAGE_PROVIDER env var (e.g. NEDURA_PET_IMAGE_PROVIDER=openrouter).

Configuration

All settings live under display.pet in config.yaml:

display:
  pet:
    enabled: false        # master on/off (true once you select a pet)
    slug: ""              # active pet; empty = first installed
    render_mode: auto      # auto | kitty | iterm | sixel | unicode | off
    scale: 0.33           # master size knob (relative to native 192x208 frames)
    unicode_cols: 0       # hard override for terminal width (0 = derive from scale)

• scale is the single master size knob. One number shrinks every surface: the desktop canvas scales its pixels by it, and the CLI/TUI derive their terminal column width from it. The half-block fallback clamps to a legibility floor — it can't shrink as far as true-pixel kitty/GUI rendering without turning to mush, so the same scale looks crisp under kitty but is floored in half-blocks.
• render_mode: auto detects kitty/iTerm2/sixel and falls back to unicode half-blocks. Set it explicitly to force a protocol or off to disable terminal rendering while keeping the pet on the desktop.
• unicode_cols pins the terminal column width independently of scale; leave it at 0 to derive width from scale.

Troubleshooting

Run nedura pets doctor — it reports:

• the pets directory and which pets are installed,
• display.pet.enabled, display.pet.slug, and the resolved active pet,
• the configured render_mode, the detected terminal graphics protocol, and the effective mode for a TTY,
• whether Pillow (used for sprite decoding) is importable.

It prints ✓ ready once a pet is installed, selected, enabled, and Pillow is available.

Common gotchas:

• A pet only shows once one is installed AND selected (enabled: true).
• Inside a pipe/redirect (no TTY), terminal rendering is disabled by design.
• The petdex npm CLI installs to ~/.codex/pets; Nedura uses its own profile-scoped <NEDURA_HOME>/pets/ instead — install through nedura pets.

See also

• The hermes-agent skill lets the agent install and switch pets for you on request (see its references/petdex.md).