Skip to content

Add Voice Module to Hermes Agent (macOS)

This guide is a complete, command-first setup for enabling Voice Mode in Hermes Agent on macOS.

Architecture Snapshot

flowchart LR
    A["Push-to-Talk (Ctrl+B)"] --> B["Hermes Voice Module"]
    B --> C["faster-whisper (STT)"]
    C --> D["Local LLM (Gemma)"]
    D --> E["Edge Neural TTS"]
    E --> F["Speaker Output"]

1. Install Homebrew Dependencies

brew install python@3.11
brew install portaudio ffmpeg
brew install --cask karabiner-elements

2. Install Hermes Agent

Official installer:

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | sh

Check installation:

which hermes
hermes

3. Fix Python Version (Critical)

Hermes requires:

Python >= 3.11

Check current Python:

python3 --version

If you still see macOS default, for example:

Python 3.9.x

Use Homebrew Python:

/opt/homebrew/bin/python3.11 --version

4. Rebuild Hermes Virtual Environment (Important)

cd ~/.hermes/hermes-agent

rm -rf venv

/opt/homebrew/bin/python3.11 -m venv venv

source venv/bin/activate

python -m ensurepip --upgrade

python -m pip install -U pip setuptools wheel

python -m pip install -e .

5. Install Voice Mode Dependencies

Activate Hermes venv:

cd ~/.hermes/hermes-agent
source venv/bin/activate

Install voice extras:

pip install -U ".[voice]"

Install missing packages explicitly:

pip install -U \
sounddevice \
soundfile \
numpy \
faster-whisper \
edge-tts

6. Test PortAudio / Microphone

python - <<'PY'
import sounddevice as sd
print(sd.query_devices())
PY

Expected output includes devices like:

MacBook Pro Microphone
MacBook Pro Speakers

7. Test Edge TTS

edge-tts \
--voice zh-CN-XiaoxiaoNeural \
--text "你好，我是 Hermes。" \
--write-media test.mp3

afplay test.mp3

8. Edit Hermes Configuration

Edit config:

nano ~/.hermes/config.yaml

Recommended config:

stt:
  enabled: true
  provider: local
  local:
    model: base

tts:
  enabled: true
  provider: edge
  edge:
    voice: zh-CN-YunxiNeural

voice:
  record_key: ctrl+b
  max_recording_seconds: 120

startup_commands:
  - "/voice on"
  - "/voice tts"

Save in nano:

Ctrl + O
Enter
Ctrl + X

9. Start Hermes

killall hermes 2>/dev/null
hermes

10. Check Voice Status

Inside Hermes:

/voice status

Healthy output:

Mode: ON
TTS: ON
STT provider: OK

11. Manual Enable (If startup_commands Did Not Apply)

/voice on
/voice tts

12. Push-To-Talk

Default key:

Ctrl + B

Behavior:

Press and hold -> start recording
Release        -> stop recording

Hermes processing loop:

STT -> LLM -> TTS

You will get automatic spoken replies.

13. Air Mouse Workflow (Optional)

Install:

brew install --cask karabiner-elements

Use:

Karabiner EventViewer

Then map:

Air mouse button -> Ctrl+B

Result:

Remote button -> Hermes voice conversation

14. Common Issues

Infinite flicker / freeze

Cause:

venv/bin/hermes self-recursion

Fix:

rm -rf venv
# then recreate venv from Step 4

No module named pip

Cause:

Broken venv

Fix:

python -m ensurepip --upgrade

Wrong Python version

Error:

requires Python >=3.11

Fix:

brew install python@3.11

TTS: OFF

Causes:

  • edge-tts not installed
  • TTS not enabled in config
  • /voice tts not executed

Fix:

pip install edge-tts

Config check:

tts:
  enabled: true

No audio input

On macOS:

System Settings
-> Privacy & Security
-> Microphone

Allow:

  • Terminal
  • iTerm2
  • VSCode

Stronger Whisper model

Use:

model: small

Or:

model: medium

More natural TTS (future options)

  • ElevenLabs
  • XTTS
  • Piper
  • OpenAI TTS

Mind Map: Deployment Checklist

mindmap
  root((Hermes + Voice Mode))
    Dependencies
      python 3.11
      portaudio
      ffmpeg
      karabiner
    Installation
      Hermes install script
      verify hermes binary
    Python and Venv
      verify python version
      rebuild venv
      reinstall package editable mode
    Voice Stack
      install .[voice]
      faster-whisper
      edge-tts
      sounddevice test
    Runtime Config
      stt local model
      tts edge voice
      record key ctrl+b
      startup voice commands
    Operation
      voice status
      push to talk
      air mouse mapping optional
    Troubleshooting
      venv recursion
      missing pip
      tts off
      microphone permission

Final System Structure

Air mouse / Ctrl+B
-> Hermes Voice
-> faster-whisper
-> local Gemma
-> Edge Neural TTS
-> real-time voice reply