Pets (Petdex Mascots)

Hermes can show an animated pet — a small mascot sprite that reacts to what the agent is doing (idle, running a tool, thinking, finishing, failing) across the CLI, TUI, and desktop app. 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.

• Pets are installed into your profile's pets/ directory (<HERMES_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:

In the terminal (CLI/TUI), Hermes 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.

The desktop app draws the pet as a floating sprite on a canvas and toggles it from Settings → Appearance.

hermes 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).

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.

In the TUI, /pet list opens an interactive picker overlay; in the desktop app it opens the Cmd+K pet palette.

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

• CLI/TUI: /hatch <description> (alias /generate-pet), or hermes pets → the generate flow.
• Desktop app: the Pokédex-style generate UI — an animated egg, hatch FX, and a draft picker.

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 Hermes 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 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 hermes tools → Image Generation. (Installing/adopting existing gallery pets needs no image backend.)
• Override the backend with the HERMES_PET_IMAGE_PROVIDER env var (e.g. HERMES_PET_IMAGE_PROVIDER=openrouter).

In the desktop app you can manage the pet two ways:

• Cmd+K → "Pets…" — browse, search, adopt, and toggle pets without leaving the keyboard (mirrors the theme picker).
• Settings → Appearance — the same gallery plus a size slider that resizes the floating mascot live as you drag.

Both adopt/toggle/resize the floating mascot in place — size changes apply instantly; adopting a new pet lights it up within a moment.

Roaming

Settings → Appearance has a Roam toggle: when enabled, the pet wanders the window on its own while the agent is idle — walking surfaces, pausing, and hopping between spots. Roaming only runs while the pet is in-window, active, and the agent is at rest; any agent-driven state (working, celebrating) immediately takes over. The toggle is off by default and persists across restarts.

Alt+wheel resizing

Hold Alt and scroll the mouse wheel over the pet to resize it in place — in the app window and on the popped-out overlay alike. The overlay zooms toward the cursor position and the resulting scale is persisted, so it survives restarts and stays in sync with the in-app pet.

Vibe reactions

Say something nice to the agent — "good bot", "thank you", "ily", <3, or a heart emoji — and the pet reacts with floating hearts (desktop) or a heart flash (CLI/TUI). Detection is a curated, token-free lexicon matched locally on each user message (no model call); it fires on affection and gratitude aimed at the agent, not general positive sentiment. All surfaces — CLI pet, TUI, desktop floating pet, and the pop-out overlay — react off the same signal.

Pop-out overlay

Shift-click the floating pet to pop it out into its own transparent, always-on-top desktop window. Out there it stays visible while Hermes is minimized (Codex-style), so a glance tells you what the agent is doing.

Gestures once it's popped out:

Only the popped-out pet shows a speech bubble (working…, thinking…, your turn, …) — in-window the app itself is the surface, so the pet stays quiet there.

The overlay is a pure puppet of the in-app pet — it carries no separate gateway connection and never appears in the dock or app switcher.

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.

Run hermes 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; Hermes uses its own profile-scoped <HERMES_HOME>/pets/ instead — install through hermes pets.

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