🐱 Hermes Visualizer Plugin

Catgirl mood animations that react to your Hermes Agent sessions in real time.

Display cute, looping catgirl animations in a terminal window that automatically respond to Hermes Agent tool calls — searching, coding, generating images, or hitting errors. Every mood has its own animation cycle!

---

✨ Features

Feature	Description
🎭 Auto Mood Tracking	Fires on post_tool_call hook — watches Hermes Agent tool calls and picks the mood automatically
🐱 8 Catgirl Moods	happy curious working thinking sad excited sleeping surprised
🎨 GIF + ASCII Fallback	Each mood has 3 looping GIF animations + an ANSI ASCII fallback; chafa renders GIFs beautifully
🔄 Live Animation Cycling	Daemon continuously loops the current mood animation until a new one arrives
➕ Grow the Library	Use the add_animation tool to download new GIFs directly into mood folders
🔧 Zero Core Modifications	Pure Hermes plugin — no patches to the agent itself

Mood Mapping

Activity	Mood	Example
Search / browse / read	🔍 curious	web_search, read_file
Terminal / patch / git	🛠 working	terminal, patch
Code / reason / analyze	💭 thinking	execute_code, delegate_task
Write / save / send	🌸 happy	write_file, send_message
Image / audio generate	✨ excited	image_generate, text_to_speech
Question / clarify	😮 surprised	clarify
Errors / failures	😿 sad	Auto-detected from result text
Session start	🌸 happy	on_session_start hook
Session end	💤 sleeping	on_session_end hook

---

📋 Requirements

• Hermes Agent v0.7.0+ (plugin support)
• chafa — terminal image renderer

  # Ubuntu / Debian
  sudo apt install chafa
  
  # Fedora
  sudo dnf install chafa
  
  # macOS
  brew install chafa
  
  # Arch
  sudo pacman -S chafa

• Python 3.10+ (stdlib only — no pip dependencies!)

---

🚀 Quick Start

1. Install the plugin

git clone https://github.com/rwcrosk-arch/hermes-visualizer-plugin   ~/.hermes/plugins/visualizer

2. Enable it in Hermes

hermes plugins enable visualizer

3. Restart Hermes Agent

Fully quit and restart Hermes so the plugin is discovered:

hermes

4. Start the visualizer daemon

In a separate terminal window/tab:

cd ~/.hermes/plugins/visualizer
python3 daemon.py

⚠️ Important: The daemon needs its own terminal window because it uses sys.stdout directly for chafa display. Running it in a background process (nohup/&) may cause path issues.

5. Use Hermes normally!

Every tool call will now trigger a mood animation. Type a prompt and watch the catgirl react! 🐱

---

🏗 Architecture

┌─────────────────────────────────┐
│      Hermes Agent Process       │
│  ┌───────────────────────────┐  │
│  │  Plugin: visualizer       │  │
│  │  ┌─────────────────────┐  │  │
│  │  │ post_tool_call hook │──┼──┼──→ mood determined from tool name
│  │  │ on_session_start    │──┼──┼──→ happy
│  │  │ on_session_end      │──┼──┼──→ sleeping
│  │  └─────────────────────┘  │  │
│  │           │              │  │
│  │           ↓              │  │
│  │   JSON to events.pipe   │  │
│  └───────────────────────────┘  │
│              │                   │
│   ┌──────────┴──────────┐       │
│   │  events.pipe (FIFO) │       │
│   └──────────┬──────────┘       │
└──────────────│──────────────────┘
               ↓
┌─────────────────────────────────┐
│   Visualizer Daemon Terminal    │
│                                 │
│   ┌─────────────────────────┐   │
│   │ daemon.py               │   │
│   │  ├─ reads pipe (O_RDWR) │   │
│   │  ├─ picks animation     │   │
│   │  ├─ loops chafa GIF     │   │
│   │  └─ clear + ANSI status │   │
│   └─────────────────────────┘   │
└─────────────────────────────────┘

---

🎮 Manual Controls

You can also manually trigger or curate animations:

# Show a mood right now
show_mood(mood="excited", message="Image generated!")

# Add a new GIF to a mood library
add_animation(
    url="https://example.com/cat.gif",
    mood="happy",
    filename="happy_4.gif"
)

# List all available moods and their files
list_moods()

---

🛠 Troubleshooting

Plugin not loading / no animations

1. Check plugin.yaml is not empty
2. Run hermes plugins list — visualizer should appear as enabled
3. If not: hermes plugins enable visualizer
4. Restart Hermes after enabling

Daemon not showing anything

# Check daemon is running
cat ~/.hermes/plugins/visualizer/daemon.pid
# If missing/pid dead, start:
python3 ~/.hermes/plugins/visualizer/daemon.py

Chafa not found / chafa errors in logs

The daemon must be started in a shell with chafa in PATH. If you see [Errno 2] No such file or directory: 'chafa':

• Make sure chafa is installed
• Start the daemon in a live shell, not via nohup or systemd

Tiled/overlapping display

The daemon clears screen with \033[2J\033[H before each frame. If chafa doesn't support your terminal, it falls back to ASCII art.

Pipe permissions

rm -f ~/.hermes/plugins/visualizer/events.pipe
# The daemon recreates the FIFO on startup

Testing the pipe manually

# With daemon running:
echo '{"mood":"happy","message":"test"}' > ~/.hermes/plugins/visualizer/events.pipe

---

📁 File Reference

File	Purpose
plugin.yaml	Hermes plugin manifest (enables discovery)
__init__.py	Plugin entry point — registers tools + hooks
schemas.py	Tool schemas for show_mood, add_animation, list_moods
tools.py	Tool handlers (writes events to named pipe)
daemon.py	Background display daemon (reads pipe, renders via chafa)
animations/	8 mood directories — each contains GIF + ASCII fallback
install.sh	Optional local installer script
skill.md	Bundled skill reference

---

🎨 Animation Assets

Each mood folder contains:

• mood_1.gif, mood_2.gif, mood_3.gif — Chafa renders these in a 3-cycle loop
• fallback_name.ansi — ASCII art backup if chafa fails

Add your own GIFs with the add_animation tool or by placing files directly into mood directories.

---

📝 Contributing

Contributions welcome!

1. Fork the repo on GitHub
2. Clone to ~/.hermes/plugins/visualizer
3. Make changes — test with the daemon running
4. Submit a PR

Ideas:

• New mood additions (e.g. angry, love, confused)
• Animated ANSI frames (no chafa dependency!)
• Daemon size/theme customization via config
• Auto-daemon-start helper

---

🧑‍💻 Maintainer

rwcrosk-arch — GitHub

Inspired by the Hermes Agent community and built with love for terminal catgirls everywhere. (=^･ω･^=)

---

📄 License

This project is licensed under the MIT License — see LICENSE for details.

Catgirl not included — but the plugins are! 🐾