hermes-waifu: app and UI for Hermes Agent

Draggable Live2D companion widget that shows Hermes Agent state, with 5 built-in models

What hermes-waifu does

The widget is an index.html page that renders Live2D models in the browser, with no server and no build step needed to open it. It includes five models: Hiyori, Haru, Mao, Rice and Senko. You drag the model to reposition it, scroll to resize it between 5 and 200 percent, and pick a model from a dropdown. Haru and Mao have per-model expression buttons, while Hiyori, Rice and Senko are motion-only. Twelve emotions, e1 to e12, map to expressions, and a state row shows idle, listening, speaking, thinking, working or error.

To connect it to Hermes Agent, two Python files, waifu.py and waifu_hook.py, are symlinked into ~/.hermes/hermes-agent/, and you run python waifu.py instead of python cli.py so lifecycle hooks are injected. The hook writes state to ~/.hermes-waifu-state.json, and the page polls /state to sync, which needs a server endpoint. A manual mode toggle ignores server state. More models can be added by editing the models array in index.html.

Key features

Live2D rendering in the browser with five built-in models
Drag to reposition and scroll to resize from 5 to 200 percent
Per-model expression controls for Haru and Mao
Twelve emotions, e1 to e12, mapped to model expressions
Agent state display for idle, listening, speaking, thinking, working and error
Manual mode that overrides the synced agent state

When to use it

Keep an animated companion on screen while Hermes Agent works
See at a glance whether the agent is thinking, working or idle
Add your own Live2D model by editing the models list

Who it is for: Hermes Agent users who want an animated desktop-style companion that reacts to what the agent is doing.

How it fits with Hermes Agent

Built for Hermes Agent, using a small hook that wraps the agent's launch script to record its state for the widget.

How to install hermes-waifu

These commands are copied from the project's README. Check the repository for the latest steps before you run them.

ln -sf /path/to/hermes-waifu/src/waifu.py ~/.hermes/hermes-agent/waifu.py
ln -sf /path/to/hermes-waifu/src/waifu_hook.py ~/.hermes/hermes-agent/waifu_hook.py

Requirements: A web browser to open index.html; the display needs no server or build step, and models must be hosted on a CDN or served locally.

Note: Syncing agent state to the page needs a server endpoint that serves /state; without one the widget runs in manual mode.

FAQ

What is hermes-waifu?

hermes-waifu is a Live2D companion widget for Hermes Agent. It runs in a browser, shows one of five built-in animated models, and can display the agent's state and emotions.

How do I install hermes-waifu?

Symlink src/waifu.py and src/waifu_hook.py into ~/.hermes/hermes-agent/, then run python waifu.py instead of python cli.py. Open index.html in a browser for the display.

What do I need to run hermes-waifu?

You need a browser to open index.html, which requires no server or build step. Live syncing of agent state needs a server endpoint that serves /state, otherwise you can use manual mode.