Petdex Mascots: An Animated Companion for Your Agent

Hermes can show an animated pet — a small mascot sprite that reacts to what the agent is doing across the CLI, TUI, and desktop app. The sprite reflects the agent's activity: idling, running a tool, thinking, finishing a task, or failing. 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 (<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 environment variable. Each surface watches the activity it already tracks and maps it to one of six animation states, using a single shared mapping so every surface behaves the same:

Rendering

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 — and otherwise 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.

Getting Started

A quick start from the CLI is simple:

hermes pets list cat        # browse the gallery (filter by substring)
hermes pets install boba --select   # install a pet and make it active
hermes pets show            # preview / animate it in your terminal
hermes pets doctor          # check your setup

The hermes pets command family covers the full lifecycle: list, install, select, scale, show, off, remove, and doctor. Inside the CLI and TUI, the /pet slash command manages the pet without leaving the session — /pet toggles it on/off, /pet list browses the gallery, /pet scale 0.5 resizes it, and /pet <slug> adopts a specific pet.

Generating a Pet With /hatch

Beyond installing pre-made pets from the gallery, Hermes can generate a brand-new pet from a text description using its own AI sprite-generation pipeline. The flow is two-step and cost-bounded. First, a handful of cheap prompt-only "what should this pet look like" base drafts are generated, and you pick one (or remix or retry). Then the hatch step uses the chosen base as a reference image to generate one grounded animation row per Hermes state, deterministically sliced into frames and packed into a standard petdex atlas — an 8×9 grid of 192×208 cells — producing a valid spritesheet you keep and could submit to petdex. Generation uses the active image-generation provider and requires reference-image grounding, preferring Nous Portal → OpenAI → OpenRouter.

The Desktop Experience

In the desktop app you can manage the pet from the Cmd+K command palette ("Pets…") or Settings → Appearance, which also hosts a live size slider. A Roam toggle lets the pet wander the window on its own while the agent is idle — walking surfaces, pausing, and hopping between spots. Hold Alt and scroll over the pet to resize it in place. Say something nice to the agent — "good bot", "thank you", "ily", or a heart emoji — and the pet reacts with floating hearts (desktop) or a heart flash (CLI/TUI); detection is a token-free, locally matched lexicon. Shift-click the pet to pop it out into its own transparent, always-on-top window: from there you can drag it anywhere, click to open a mini composer, or double-click to toggle the app window.

Configuration

All settings live under display.pet in config.yaml: enabled (master on/off), slug (active pet), render_mode (auto, kitty, iterm, sixel, unicode, or off), and scale — the single master size knob that shrinks every surface. render_mode: auto detects kitty/iTerm2/sixel and falls back to Unicode half-blocks. If something looks wrong, run hermes pets doctor, which reports the installed pets, the enabled state, the configured render mode and detected protocol, and whether Pillow is importable.

Key Takeaways

• Pets are purely cosmetic, off by default, and install into each profile's own pets/ directory.
• A single state mapping drives animation across the CLI, TUI, and desktop app.
• The /hatch command generates a brand-new pet from a text description via a reference-grounded image pipeline.
• The desktop adds Roam wandering, Alt+wheel resizing, vibe reactions, and a pop-out overlay.
• hermes pets doctor diagnoses installations, protocol detection, and dependencies.