Petdex Skill
Browse, install, and select animated "pet" mascots from the public
petdex gallery. An installed pet
reacts to agent activity (idle, running a tool, reviewing, error, done) across
the Hermes CLI, TUI, and desktop app. This skill drives the hermes pets CLI
and the display.pet config — it does not generate sprites.
When to Use
- The user wants a desktop/terminal mascot or asks about "pets" / petdex.
- The user wants to change, preview, or disable the active pet.
- Diagnosing why a pet isn't showing (terminal graphics support, config).
Prerequisites
- Network access to
petdex.dev for the gallery/manifest (read-only, no auth).
- Pillow (a core Hermes dependency) for sprite decoding — already installed.
- For full-fidelity terminal rendering: a graphics-capable terminal (kitty,
Ghostty, WezTerm, iTerm2, or sixel). Otherwise a truecolor Unicode
half-block fallback is used automatically.
How to Run
Use the terminal tool to run hermes pets <subcommand>.
Quick Reference
| Goal |
Command |
| Browse the gallery |
hermes pets list (add a substring to filter: hermes pets list cat) |
| List installed pets |
hermes pets list --installed |
| Install a pet |
hermes pets install <slug> (add --select to make it active) |
| 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 in terminal |
hermes pets show [slug] [--cycle] [--state run] |
| Disable the pet |
hermes pets off |
| Remove a pet |
hermes pets remove <slug> |
| Diagnose setup |
hermes pets doctor |
Procedure
- Find a pet:
hermes pets list <query> and note its slug.
- Install + activate:
hermes pets install <slug> --select.
- Preview it:
hermes pets show (Ctrl+C to stop).
- Confirm setup:
hermes pets doctor — shows the resolved pet, configured
render mode, detected terminal graphics protocol, and effective mode.
Pets install into <HERMES_HOME>/pets/<slug>/ (profile-aware). Selecting a pet
writes display.pet.slug + display.pet.enabled to config.yaml.
Configuration
Under display.pet in config.yaml:
enabled (bool) — master on/off.
slug (str) — active pet; empty = first installed.
render_mode — auto (detect) | kitty | iterm | sixel | unicode | off.
scale (float) — on-screen size of the native 192×208 frames (default 0.33,
clamped 0.1–3.0). One knob resizes every surface; set it with
hermes pets scale <factor>, the /pet scale slash command, or the desktop
Appearance slider.
unicode_cols (int) — width in columns for the Unicode fallback.
Pitfalls
- 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.
Verification
hermes pets doctor reports ✓ ready when a pet is installed, selected,
enabled, and Pillow is importable.
1---2name: petdex3description: Install and select animated petdex mascots for Hermes.4license: MIT5metadata:6 source: https://skillmd.com/skills/samin12/petdex7 hermes-tags: "petdex, mascot, display, cli, tui, desktop"8 hermes-category: productivity9 hermes-homepage: "https://petdex.dev"10 version: 1.0.011 author: Hermes Agent12 platforms: "linux, macos, windows"13---1415# Petdex Skill1617Browse, install, and select animated "pet" mascots from the public18[petdex](https://github.com/crafter-station/petdex) gallery. An installed pet19reacts to agent activity (idle, running a tool, reviewing, error, done) across20the Hermes CLI, TUI, and desktop app. This skill drives the `hermes pets` CLI21and the `display.pet` config — it does not generate sprites.2223## When to Use2425- The user wants a desktop/terminal mascot or asks about "pets" / petdex.26- The user wants to change, preview, or disable the active pet.27- Diagnosing why a pet isn't showing (terminal graphics support, config).2829## Prerequisites3031- Network access to `petdex.dev` for the gallery/manifest (read-only, no auth).32- Pillow (a core Hermes dependency) for sprite decoding — already installed.33- For full-fidelity terminal rendering: a graphics-capable terminal (kitty,34 Ghostty, WezTerm, iTerm2, or sixel). Otherwise a truecolor Unicode35 half-block fallback is used automatically.3637## How to Run3839Use the `terminal` tool to run `hermes pets <subcommand>`.4041## Quick Reference4243| Goal | Command |44| --- | --- |45| Browse the gallery | `hermes pets list` (add a substring to filter: `hermes pets list cat`) |46| List installed pets | `hermes pets list --installed` |47| Install a pet | `hermes pets install <slug>` (add `--select` to make it active) |48| Set the active pet | `hermes pets select <slug>` (omit slug for a picker) |49| Resize the pet everywhere | `hermes pets scale <factor>` (e.g. `0.5`, clamped 0.1–3.0) |50| Preview/animate in terminal | `hermes pets show [slug] [--cycle] [--state run]` |51| Disable the pet | `hermes pets off` |52| Remove a pet | `hermes pets remove <slug>` |53| Diagnose setup | `hermes pets doctor` |5455## Procedure56571. Find a pet: `hermes pets list <query>` and note its `slug`.582. Install + activate: `hermes pets install <slug> --select`.593. Preview it: `hermes pets show` (Ctrl+C to stop).604. Confirm setup: `hermes pets doctor` — shows the resolved pet, configured61 render mode, detected terminal graphics protocol, and effective mode.6263Pets install into `<HERMES_HOME>/pets/<slug>/` (profile-aware). Selecting a pet64writes `display.pet.slug` + `display.pet.enabled` to `config.yaml`.6566## Configuration6768Under `display.pet` in `config.yaml`:6970- `enabled` (bool) — master on/off.71- `slug` (str) — active pet; empty = first installed.72- `render_mode` — `auto` (detect) | `kitty` | `iterm` | `sixel` | `unicode` | `off`.73- `scale` (float) — on-screen size of the native 192×208 frames (default 0.33,74 clamped 0.1–3.0). One knob resizes every surface; set it with75 `hermes pets scale <factor>`, the `/pet scale` slash command, or the desktop76 Appearance slider.77- `unicode_cols` (int) — width in columns for the Unicode fallback.7879## Pitfalls8081- A pet only shows once one is installed AND selected (`enabled: true`).82- Inside a pipe/redirect (no TTY) terminal rendering is disabled by design.83- The petdex npm CLI installs to `~/.codex/pets`; Hermes uses its own84 profile-scoped `<HERMES_HOME>/pets/` instead — install through `hermes pets`.8586## Verification8788- `hermes pets doctor` reports `✓ ready` when a pet is installed, selected,89 enabled, and Pillow is importable.