ray
90 lines
3.5 KiB
Markdown
90 lines
3.5 KiB
Markdown
---
|
||
name: petdex
|
||
description: Install and select animated petdex mascots for Hermes.
|
||
version: 1.0.0
|
||
author: Hermes Agent
|
||
license: MIT
|
||
platforms: [linux, macos, windows]
|
||
metadata:
|
||
hermes:
|
||
tags: [petdex, mascot, display, cli, tui, desktop]
|
||
category: productivity
|
||
homepage: https://petdex.dev
|
||
---
|
||
|
||
# Petdex Skill
|
||
|
||
Browse, install, and select animated "pet" mascots from the public
|
||
[petdex](https://github.com/crafter-station/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
|
||
|
||
1. Find a pet: `hermes pets list <query>` and note its `slug`.
|
||
2. Install + activate: `hermes pets install <slug> --select`.
|
||
3. Preview it: `hermes pets show` (Ctrl+C to stop).
|
||
4. 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.
|