sidebar_position: 11 title: "Pets (Petdex Mascots)" description: "Adopt an animated mascot that reacts to agent activity across the CLI, TUI, and desktop app"
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/ directory
(<HERMES_HOME>/pets/<slug>/), so each profile keeps its
own set.display.pet.slug and display.pet.enabled to
config.yaml — nothing is stored as a secret or env var.| 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 |
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.
# Browse the gallery (filter by substring)
hermes pets list
hermes pets list cat
# Install a pet and make it active in one step
hermes pets install boba --select
# Preview / animate it in your terminal (Ctrl+C to stop)
hermes pets show
# Check your setup
hermes pets doctor
hermes pets commands| Goal | Command |
|---|---|
| Browse the gallery | hermes pets list [query] [--limit N] |
| List installed pets | hermes pets list --installed |
| Install a pet | hermes pets install <slug> [--select] [--force] |
| Set the active pet | hermes pets select [slug] (omit slug for a picker) |
| Resize the pet everywhere | hermes pets scale <factor> (e.g. 0.5, clamped 0.1–3.0) |
| Preview/animate | hermes pets show [slug] [--state <s>] [--cycle] [--once] [--mode <m>] [--scale <f>] |
| Disable the pet | hermes pets off |
| Remove an installed pet | hermes pets remove <slug> |
| Diagnose setup | hermes pets doctor |
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)./pet slash commandInside 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.
/hatch)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.
/hatch <description> (alias /generate-pet), or hermes pets → the generate flow.How generation works (a two-step, cost-bounded flow):
petdex submit.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.
hermes tools → Image Generation. (Installing/adopting existing gallery pets needs no image backend.)HERMES_PET_IMAGE_PROVIDER env var (e.g. HERMES_PET_IMAGE_PROVIDER=openrouter).In the desktop app you can manage the pet two ways:
Both adopt/toggle/resize the floating mascot in place — size changes apply instantly; adopting a new pet lights it up within a moment.
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.
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.
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.
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:
| Gesture | Action |
|---|---|
| Drag | Move the pet anywhere on screen, even outside the app. Its spot and in/out state persist across restarts. |
| Single-click | Open a mini composer to send a prompt to the most recent session — without surfacing the app. |
| Double-click | Toggle the app window: minimize it if it's up front, restore it if it's hidden. |
| Shift-click | Pop the pet back into the window. |
| Mail icon | Appears only when a turn finished while you were away; click to raise the app on the most recent thread (and mark it read). |
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:
display.pet.enabled, display.pet.slug, and the resolved active pet,render_mode, the detected terminal graphics protocol, and the
effective mode for a TTY,It prints ✓ ready once a pet is installed, selected, enabled, and Pillow is
available.
Common gotchas:
enabled: true).~/.codex/pets; Hermes uses its own
profile-scoped <HERMES_HOME>/pets/ instead — install through hermes pets.hermes-agent skill
lets the agent install and switch pets for you on request (see its
references/petdex.md).