Petdex - Animated Mascots Setup Guide¶
Add an animated desktop mascot to your Hermes agent. Petdex provides a collection of pixel-art animated companions that react to agent activity, giving your Hermes instance personality and visual feedback.
Source: nousresearch/hermes-agent via skills.sh
Installation¶
npx skills add nousresearch/hermes-agent --skill petdex
Prerequisites¶
- Hermes Agent installed and running
- Node.js 18+
- Display server (X11/Wayland on Linux; native on macOS)
Usage¶
List Available Mascots¶
# Browse the mascot catalog
hermes petdex list
Select a Mascot¶
# Select by name
hermes petdex select blinky
# Random selection
hermes petdex random
Configure Behavior¶
Mascots react to agent states:
# Show current mascot settings
hermes petdex config
# Set idle animation speed
hermes petdex config --idle-speed 2
# Enable reaction to errors
hermes petdex config --react-errors true
Available Mascots¶
| Name | Style | Description |
|---|---|---|
blinky |
Pixel | Classic blinking eye companion |
ghost |
Pixel | Friendly ghost that floats around |
cat |
Pixel | Animated cat with idle behaviors |
robot |
Pixel | Tiny robot with mechanical animations |
fox |
Pixel | Playful fox mascot |
Run hermes petdex list for the latest catalog.
States & Animations¶
Mascots respond to these agent states:
| State | Behavior |
|---|---|
| Idle | Wandering, blinking, stretching |
| Working | Focused look, typing animation |
| Error | Alert expression, shaking |
| Success | Happy bounce, sparkle effect |
| Waiting | Tapping foot, looking around |
Integration Tips¶
Auto-start with Hermes¶
Add to your Hermes config (~/.hermes/config.yaml):
petdex:
enabled: true
mascot: random
idle_speed: 2
react_errors: true
Use as Agent Health Indicator¶
The mascot's visual state provides at-a-glance agent health: - Happy/active = agent running normally - Error state = check agent logs immediately - Frozen = agent process may be hung
Troubleshooting¶
| Issue | Solution |
|---|---|
| Mascot not appearing | Check display server is running (echo $DISPLAY) |
| Mascot frozen | Restart with hermes petdex restart |
| High CPU usage | Lower idle speed: hermes petdex config --idle-speed 1 |
| No mascots listed | Reinstall: npx skills add nousresearch/hermes-agent --skill petdex |
Integration with CorpusIQ¶
CorpusIQ is the connector layer that lets AI assistants read the systems a business already runs on - accounting, payments, CRM, email, files and analytics - and answer with the source named. It is read-only by design: it retrieves data and never writes to, or acts in, a connected system, which is what makes it safe to point at live accounts.
This page is part of the CorpusIQ directory, the reference we maintain for the MCP server and agent-skill ecosystem. Run alongside CorpusIQ, a third-party server like this one can be combined with a company's own business data in a single answer.