Agent Vibes TTS - Complete Installation Guide

Time Required: ~18 minutes Difficulty: Intermediate System: macOS (Apple Silicon or Intel)

Prerequisites Check

Before starting, verify you have:

Requirement	Check Command	Min Version
macOS	`sw_vers`	10.15+
Homebrew	`brew --version`	Any recent
Node.js	`node --version`	16.0.0+
Python	`python3 --version`	3.10.0+
Git	`git --version`	Any recent

Installation Overview (5 Phases)

Phase 1: System Dependencies     (~5 min)
    ├─ Bash 5.x
    ├─ sox, ffmpeg, util-linux
    └─ espeak-ng

Phase 2: Agent Vibes Install     (~5 min)
    ├─ Interactive installer
    ├─ Provider selection (Piper)
    ├─ Voice selection
    └─ Configuration

Phase 3: Piper TTS + Voices       (~5 min)
    ├─ Piper via pipx
    ├─ Download FR voices (4)
    └─ Download EN voices (12)

Phase 4: Configuration            (~2 min)
    ├─ Set provider: piper
    ├─ Set voice: fr_FR-tom-medium
    └─ Test audio

Phase 5: Verification             (~1 min)
    ├─ Test in Claude Code
    └─ Verify hooks active

Phase 1: System Dependencies

Step 1.1: Install Bash 5.x

Agent Vibes requires Bash 5.x (macOS ships with 3.2).

# Install Bash 5.x
brew install bash

# Verify installation
/opt/homebrew/bin/bash --version
# Expected: GNU bash, version 5.x

Why: Agent Vibes scripts use Bash 5.x features (associative arrays, etc.)

Step 1.2: Install Audio Tools

# Install audio processing tools
brew install sox ffmpeg util-linux

# Verify sox
sox --version

# Verify ffmpeg
ffmpeg -version

# Verify flock (from util-linux)
/opt/homebrew/opt/util-linux/bin/flock --version

Note: util-linux is "keg-only" (not symlinked), but Agent Vibes finds it automatically.

Step 1.3: Install espeak-ng (Piper Dependency)

# Install espeak-ng
brew install espeak-ng

# Verify installation
espeak-ng --version

Why: Piper TTS requires libespeak-ng library for phoneme processing.

Checkpoint 1: Dependencies Installed ✅

# Verify all dependencies
command -v /opt/homebrew/bin/bash && \
command -v sox && \
command -v ffmpeg && \
command -v espeak-ng && \
echo "✅ All dependencies installed"

Phase 2: Agent Vibes Installation

Step 2.1: Launch Interactive Installer

# Navigate to your Claude Code project
cd /path/to/your/project

# Launch installer (interactive, 4 pages)
npx agentvibes install

Expected: ASCII art banner + welcome screen

Step 2.2: Navigate Installation Pages

Page 1/4: System Dependencies

Review detected dependencies
All should show ✓ (green checkmark)
Click "Next →"

Page 2/4: Provider Selection

Options: macOS Say, Piper TTS, Termux SSH
Select: Piper TTS (best quality, offline)
Click "Next →"

Page 3/4: Voice Selection

For French: Select fr_FR-tom-medium (male) or fr_FR-siwis-medium (female)
For English: Select en_US-ryan-high (best quality)
Click "Next →"

Page 4/4: Audio Settings

Reverb: Select Light (recommended)
Background Music: Select Disabled (avoid distraction)
Verbosity: Select Low (less chatty)
Click "Start Installation"

Step 2.3: Installation Progress

Agent Vibes will install:

34 slash commands
TTS scripts (40 bash scripts)
Personality templates
16 background music tracks
7 config files

Expected output:

✔ Installed 34 slash commands!
✔ Installed TTS scripts!
✔ Installed personality templates!
✔ Installed 16 background music tracks!
✔ Installed 7 config files!

✅ AgentVibes is Ready!

Checkpoint 2: Agent Vibes Installed ✅

# Verify installation
ls -la .claude/hooks/play-tts.sh
ls -la .claude/commands/agent-vibes/
ls -la .claude/audio/tracks/

# Check provider config
cat .claude/tts-provider.txt
# Expected: "macos" or "piper"

Phase 3: Piper TTS + Voice Models

Step 3.1: Install Piper TTS via pipx

If you chose Piper provider, Agent Vibes will attempt to install it. If it fails, manual installation:

# Install Piper via pipx (Python package manager)
pipx install piper-tts

# Verify installation
piper --help

Common Issue: Precompiled binary fails with libespeak-ng.1.dylib error.

Solution: pipx install piper-tts works reliably (Python version, not binary).

Step 3.2: Download French Voices

# Navigate to voice storage
cd ~/.claude/piper-voices

# Download 4 French voice models
curl -L -o fr_FR-tom-medium.onnx \
  "https://huggingface.co/rhasspy/piper-voices/resolve/main/fr/fr_FR/tom/medium/fr_FR-tom-medium.onnx"
curl -L -o fr_FR-tom-medium.onnx.json \
  "https://huggingface.co/rhasspy/piper-voices/resolve/main/fr/fr_FR/tom/medium/fr_FR-tom-medium.onnx.json"

curl -L -o fr_FR-siwis-medium.onnx \
  "https://huggingface.co/rhasspy/piper-voices/resolve/main/fr/fr_FR/siwis/medium/fr_FR-siwis-medium.onnx"
curl -L -o fr_FR-siwis-medium.onnx.json \
  "https://huggingface.co/rhasspy/piper-voices/resolve/main/fr/fr_FR/siwis/medium/fr_FR-siwis-medium.onnx.json"

curl -L -o fr_FR-upmc-medium.onnx \
  "https://huggingface.co/rhasspy/piper-voices/resolve/main/fr/fr_FR/upmc/medium/fr_FR-upmc-medium.onnx"
curl -L -o fr_FR-upmc-medium.onnx.json \
  "https://huggingface.co/rhasspy/piper-voices/resolve/main/fr/fr_FR/upmc/medium/fr_FR-upmc-medium.onnx.json"

curl -L -o fr_FR-mls-medium.onnx \
  "https://huggingface.co/rhasspy/piper-voices/resolve/main/fr/fr_FR/mls/medium/fr_FR-mls-medium.onnx"
curl -L -o fr_FR-mls-medium.onnx.json \
  "https://huggingface.co/rhasspy/piper-voices/resolve/main/fr/fr_FR/mls/medium/fr_FR-mls-medium.onnx.json"

Size: ~60-73MB per voice (4 voices = ~260MB total)

Step 3.3: Download English Voices (Optional)

Agent Vibes auto-downloads 12 English voices during installation. Verify:

ls ~/.claude/piper-voices/en_US-*.onnx

Expected: 12 files (ryan, amy, lessac, bryce, etc.)

Checkpoint 3: Voices Downloaded ✅

# Count voices
ls ~/.claude/piper-voices/*.onnx | wc -l
# Expected: 15+ files (12 EN + 4 FR minimum)

# Test French voice manually
echo "Bonjour, je suis Claude et je parle français" | \
  piper -m ~/.claude/piper-voices/fr_FR-tom-medium.onnx \
  --output-file /tmp/test-fr.wav && afplay /tmp/test-fr.wav

Phase 4: Configuration

Step 4.1: Set Piper as Provider

# Switch to Piper TTS (if not already set)
echo "piper" > .claude/tts-provider.txt

# Verify
cat .claude/tts-provider.txt
# Expected: "piper"

Step 4.2: Set French Male Voice

# Set default voice
echo "fr_FR-tom-medium" > .claude/tts-voice.txt

# Verify
cat .claude/tts-voice.txt
# Expected: "fr_FR-tom-medium"

Step 4.3: Test Audio Generation

# Test TTS pipeline manually
~/.claude/hooks/play-tts.sh "Ceci est un test audio"

Expected: Audio plays with French male voice.

Troubleshooting: If no audio, see Troubleshooting Guide.

Checkpoint 4: Configuration Complete ✅

# Verify config files
test -f .claude/tts-provider.txt && \
test -f .claude/tts-voice.txt && \
test -f .claude/hooks/play-tts.sh && \
echo "✅ Configuration complete"

Phase 5: Verification in Claude Code

Step 5.1: Launch Claude Code

# Start Claude Code session
claude

Step 5.2: Test TTS Commands

# In Claude, run:
/agent-vibes:whoami
# Expected: Shows current voice and provider

/agent-vibes:list
# Expected: Lists all 15+ voices

# Test TTS with simple request
> "Dis-moi bonjour en français"
# Expected: Audio response in French

Step 5.3: Verify Hooks Active

# Exit Claude, check hook was triggered
ls -la /tmp/tts-*.wav
# Expected: Temporary audio files

# Check last played audio
ls -la ~/.claude/tts-last-played.wav
# Expected: File exists

Checkpoint 5: Verification Complete ✅

# Final verification
cat .claude/tts-provider.txt && \
cat .claude/tts-voice.txt && \
piper --help > /dev/null 2>&1 && \
ls ~/.claude/piper-voices/*.onnx | wc -l && \
echo "✅ Installation successful!"

Post-Installation Configuration

Reduce Verbosity (Recommended)

# In Claude Code
/agent-vibes:verbosity low

Why: Reduces audio narration frequency, less distracting.

Hide 34 Commands (Optional)

# In Claude Code
/agent-vibes:hide

Why: Declutters command palette. Use /agent-vibes:show to unhide.

Disable Background Music

# In Claude Code
/agent-vibes:background-music off

Why: Background music can be distracting during focus work.

Set Project Mute (Optional)

# Mute TTS for this project only
touch .claude/agentvibes-muted

Why: Some projects don't need audio (e.g., documentation-only repos).

Performance Benchmarks

System: M1 MacBook Pro, 16GB RAM, macOS Sequoia 24.6.0

Metric	Piper Medium	Piper High	macOS Say
Audio Generation	~200ms	~400ms	Instant
Total Latency	~280ms	~480ms	~50ms
RAM Usage	~50MB	~70MB	~10MB
CPU Burst	80% (200ms)	90% (400ms)	5% (50ms)
Voice Quality	⭐️⭐️⭐️⭐️	⭐️⭐️⭐️⭐️⭐️	⭐️⭐️⭐️
Offline	✅	✅	✅

Recommendation: Piper Medium = best quality/speed trade-off.

Disk Usage

Component	Size	Location
Piper TTS	~5MB	`~/.local/pipx/venvs/piper-tts/`
Voice Models	~1GB	`~/.claude/piper-voices/` (15 voices × 60MB)
Background Music	~300MB	`.claude/audio/tracks/` (16 tracks)
Scripts	~2MB	`.claude/hooks/` (40 bash scripts)
Total	~1.3GB	-

Cleanup Tip: Delete unused voices to save space.

Uninstall Instructions

Automated Uninstall

# Uninstall Agent Vibes completely
npx agentvibes uninstall --yes

Manual Cleanup

# Remove Agent Vibes files
rm -rf .claude/hooks/*vibes*
rm -rf .claude/commands/agent-vibes/
rm -rf .claude/audio/

# Remove Piper TTS
pipx uninstall piper-tts

# Remove voice models
rm -rf ~/.claude/piper-voices/

# Remove config files
rm .claude/tts-provider.txt
rm .claude/tts-voice.txt
rm .claude/agentvibes-muted 2>/dev/null
rm ~/.agentvibes-muted 2>/dev/null

Common Installation Issues

Issue 1: `libespeak-ng.1.dylib` Not Found

Symptom:

dyld[xxx]: Library not loaded: @rpath/libespeak-ng.1.dylib

Solution:

# Install espeak-ng
brew install espeak-ng

# Reinstall Piper via pipx (not binary)
pipx uninstall piper-tts
pipx install piper-tts

Issue 2: `flock` Warning (Optional Tool)

Symptom:

⚠ flock - TTS queue locking

Impact: Minor. TTS works without flock, may have audio collision with rapid messages.

Solution (optional):

# flock is in util-linux, already installed
# Add to PATH if needed
export PATH="/opt/homebrew/opt/util-linux/bin:$PATH"

Issue 3: Agent Vibes Installer Exits

Symptom:

ExitPromptError: User force closed the prompt

Cause: Interactive installer requires user input (can't be automated).

Solution: Run npx agentvibes install in interactive terminal (not via script).

Issue 4: No Audio After Installation

Diagnostic:

# 1. Check mute status
ls .claude/agentvibes-muted ~/.agentvibes-muted

# 2. Check provider
cat .claude/tts-provider.txt

# 3. Test Piper manually
echo "Test" | piper -m ~/.claude/piper-voices/fr_FR-tom-medium.onnx \
  --output-file /tmp/test.wav && afplay /tmp/test.wav

Solutions: See Troubleshooting Guide.

Next Steps

After installation:

Voice Catalog - Explore 15 voices and choose your favorite
README - Learn essential commands and use cases
Troubleshooting - Solve common issues
AI Ecosystem - TTS in broader AI context

Resources

Agent Vibes GitHub: https://github.com/paulpreibisch/AgentVibes
Piper Voices Repository: https://huggingface.co/rhasspy/piper-voices
Piper Voice Samples: https://rhasspy.github.io/piper-samples/
Agent Vibes Website: https://agentvibes.org

Installation guide maintained by Claude Code Ultimate Guide Last updated: 2026-01-22 | Tested on: macOS Sequoia 24.6.0 (Apple Silicon)

FilesExpand file tree

installation.md

Latest commit

History

installation.md

File metadata and controls

Agent Vibes TTS - Complete Installation Guide

Prerequisites Check

Installation Overview (5 Phases)

Phase 1: System Dependencies

Step 1.1: Install Bash 5.x

Step 1.2: Install Audio Tools

Step 1.3: Install espeak-ng (Piper Dependency)

Checkpoint 1: Dependencies Installed ✅

Phase 2: Agent Vibes Installation

Step 2.1: Launch Interactive Installer

Step 2.2: Navigate Installation Pages

Step 2.3: Installation Progress

Checkpoint 2: Agent Vibes Installed ✅

Phase 3: Piper TTS + Voice Models

Step 3.1: Install Piper TTS via pipx

Step 3.2: Download French Voices

Step 3.3: Download English Voices (Optional)

Checkpoint 3: Voices Downloaded ✅

Phase 4: Configuration

Step 4.1: Set Piper as Provider

Step 4.2: Set French Male Voice

Step 4.3: Test Audio Generation

Checkpoint 4: Configuration Complete ✅

Phase 5: Verification in Claude Code

Step 5.1: Launch Claude Code

Step 5.2: Test TTS Commands

Step 5.3: Verify Hooks Active

Checkpoint 5: Verification Complete ✅

Post-Installation Configuration

Reduce Verbosity (Recommended)

Hide 34 Commands (Optional)

Disable Background Music

Set Project Mute (Optional)

Performance Benchmarks

Disk Usage

Uninstall Instructions

Automated Uninstall

Manual Cleanup

Common Installation Issues

Issue 1: libespeak-ng.1.dylib Not Found

Issue 2: flock Warning (Optional Tool)

Issue 3: Agent Vibes Installer Exits

Issue 4: No Audio After Installation

Next Steps

Resources

Issue 1: `libespeak-ng.1.dylib` Not Found

Issue 2: `flock` Warning (Optional Tool)