hermes-waifu

Live2D waifu display for Hermes Agent with expression controls.

What is this?

Live animated waifu you can drag around, resize, and control expressions. No TTS, no chat, no complexity.

Features:

• Live2D model rendering in browser
• 5 built-in models (Hiyori, Haru, Mao, Rice, Senko)
• Drag to reposition, scroll to resize (5%-200%)
• Model selector dropdown
• Expression controls (per-model)
• Emotion system (e1-e12)
• Agent state display (idle/thinking/speaking/etc)
• Manual mode toggle (override auto state)
• Minimal dependencies (4 CDN scripts)

Expression System

Three rows of controls at the bottom:

Row	What it does
States	Agent states: idle, listening, speaking, thinking, working, error
Expressions	Per-model face buttons — Haru (f00-f07), Mao (exp_01-08), motion-only models show "motion-only"
Emotions	e1-e12 mapped to names (happy, amused, empathetic, curious, confused, surprised, embarrassed, confident, annoyed, overwhelmed, determined, affectionate)

Emotion→expression mapping matches waifu_hook.py:

• Haru: e1(happy)→f04, e4(curious)→f01, e5(confused)→f06, etc.
• Mao: e1(happy)→exp_04, e4(curious)→exp_07, e9(annoyed)→exp_08, etc.

Active expression/emotion is highlighted with a glow.

Expression Details

Haru (f00-f07)

ID	Face
f00	neutral
f01	surprised/excited
f02	angry/sad
f03	worried/concerned
f04	happy (closed eyes)
f05	shocked
f06	sad
f07	pouty

Mao (exp_01-exp_08)

ID	Face
exp_01	neutral
exp_02	closed smile (^_^)
exp_03	neutral alt
exp_04	excited sparkle
exp_05	sad
exp_06	shy/blush
exp_07	worried
exp_08	angry

Motion-only (Hiyori, Rice, Senko)

No expression files — only idle/tap motions. Emotion buttons exist but have no visual effect on the model face.

Usage

Live2D Display

Open index.html in a browser. No server needed, no build step. Pure client-side.

Controls:

• Click expression/emotion buttons to change the face
• Scroll over model to resize
• Drag to reposition
• ⏸/▶ button toggles manual mode (ignores server state)
• Model selector in top-right header

Hermes Agent Integration

Symlink src/waifu.py and src/waifu_hook.py into ~/.hermes/hermes-agent/:

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

Then run python waifu.py instead of python cli.py to get lifecycle hooks injected.

waifu_hook.py writes state to ~/.hermes-waifu-state.json. The HTML polls /state to sync (requires a server endpoint, or use manual mode).

Adding more models

Edit the models array in index.html:

const models = [
  {
    name: "YourModel",
    url: "https://cdn.jsdelivr.net/.../model.model3.json",
    type: "expression",           // or "motion-only"
    expressions: ["face1","face2"] // only if type="expression"
  }
];

Models must be hosted online (CDN) or served locally.

License

MIT No Attribution - see LICENSE