Hermes Piper Plugin

Makes Piper TTS the default provider instead of Microsoft Edge TTS.

Zero modifications to the Hermes repo. No fork required. The plugin monkey-patches tools.tts_tool.DEFAULT_PROVIDER at plugin load time.

Why

• Piper is local, free, CPU-only — no API key, no cloud dependency
• Edge TTS requires internet access and ffmpeg for Telegram voice bubbles
• This eliminates the need to maintain a fork just to change the default

How it works

# At plugin load time, this single line runs:
tools.tts_tool.DEFAULT_PROVIDER = "piper"

That's it. DEFAULT_PROVIDER is read at call time, so changing it after import is safe. The plugin also logs the effective default at session start.

Installation

# Install from the internal Hermes package registry
pip install hermes-piper-plugin

# Or install in editable mode for development
git clone https://code.lazyworkhorse.net/gortium/hermes-piper-plugin.git
cd hermes-piper-plugin
pip install -e .

Note: The plugin used to be installed via hermes plugins install from the old flat layout. It is now a proper pip package. The entry point hermes_agent.plugins is registered automatically when you install the package — Hermes discovers it on next startup.

Testing

cd /path/to/hermes-piper-plugin
pip install pytest pyyaml
python -m pytest tests/ -v

Tests cover:

• Manifest validation — confirms plugin.yaml structure and required fields
• Monkey-patch logic — verifies DEFAULT_PROVIDER is changed to 'piper'
• Idempotency — calling _apply_piper_patch() twice is safe
• Error handling — import failures and exceptions are caught gracefully
• Lifecycle hooks — on_session_start fires without errors
• Plugin registration — register() wires tools, hooks, and logging correctly

Config

The plugin changes the default provider. You can still override per session by setting tts.provider in ~/.hermes/config.yaml:

tts:
  provider: elevenlabs      # override per-session
  voice: "Adam"             # ElevenLabs voice

Requires

• piper-tts Python package (installed via pip)
• Piper voice models (downloaded automatically on first use, ~50MB each)

Safety

• If piper-tts is not installed, the TTS tool returns an error asking the user to install it — no silent fallback to Edge
• Removing the plugin restores the original Hermes default (Edge)
• No data loss risk. No changes to any file in the Hermes repo.