Skip to main content
Mibyan 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.

​
How it works

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

​
Rendering

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

​
Quick start (CLI)

​
mibyan pets commands

mibyan 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.
In the TUI, /pet list opens an interactive picker overlay; in the desktop app it opens the Cmd+K pet palette.

​
Generating a pet (/hatch)

Beyond installing pre-made pets from the gallery, Mibyan can generate a brand-new pet from a text description — its own AI sprite-generation pipeline.
  • CLI/TUI: /hatch <description> (alias /generate-pet), or mibyan 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 Mibyan 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 mibyan tools → Image Generation. (Installing/adopting existing gallery pets needs no image backend.)
  • Override the backend with the mibyan_PET_IMAGE_PROVIDER env var (e.g. mibyan_PET_IMAGE_PROVIDER=openrouter).

​
Desktop app

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 Mibyan 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.

​
Configuration

All settings live under display.pet in config.yaml:
  • 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 mibyan 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; Mibyan uses its own profile-scoped <mibyan_HOME>/pets/ instead — install through mibyan pets.

​
See also

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