Agent Vibes TTS - Text-to-Speech for Claude Code

Status: Community MCP Server (optional) Version: 3.0.0 Maintainer: Paul Preibisch License: Apache 2.0

Quick Decision Matrix

Should you install Agent Vibes? Use this matrix:

Use Case	Recommendation	Reason
Code reviews (listen while multitasking)	⭐️⭐️⭐️⭐️⭐️	Audio narration frees your eyes
Long debugging sessions	⭐️⭐️⭐️⭐️	Audio notifications keep you informed
Focus-intensive work	⚠️ Can be distracting	Consider mute during deep work
Offline TTS (no internet)	✅ Perfect fit	Piper TTS is 100% offline
Premium voice quality	❌ Use ElevenLabs	Agent Vibes = free, good quality
French language	⭐️⭐️⭐️⭐️	4 FR voices (128 speakers)
English language	⭐️⭐️⭐️⭐️⭐️	12 EN voices (high quality)

30-Second Overview

Agent Vibes adds audible narration to Claude Code responses using:

15 voices (12 English, 4 French including 124 speakers)
100% free (Piper TTS + macOS Say)
100% offline (no cloud dependency)
18-minute installation (5 phases with checkpoints)
34 slash commands for voice control

Installation: Complete Guide | Quick Workflow Usage: Voice Catalog | Troubleshooting

How It Works

Architecture

Claude Code Response
    ↓
.claude/hooks/play-tts.sh (Router)
    ↓
[Mute Check] → Exit if muted
    ↓
[Provider Manager]
    ├─ piper   → Piper TTS (offline, neural voices)
    ├─ macos   → macOS Say (native, instant)
    └─ termux  → Android via SSH
    ↓
[Voice Processing]
    ├─ Load voice model (~60MB)
    ├─ Generate audio (~200ms)
    ├─ Apply effects (reverb, echo)
    └─ Mix background music (optional)
    ↓
[Audio Output] → afplay (macOS) / speaker

Performance (M1 Mac):

Audio generation: ~200ms
Total latency: ~280ms (generation + effects + playback)
RAM usage: ~50MB
CPU: ~80% burst (200ms), then idle

Quick Start (5 Minutes)

Prerequisites

macOS with Homebrew
Bash 5.x (Agent Vibes will help install)
Node.js 16+ (for installation)

Installation

# 1. Install Agent Vibes (interactive, 4 pages)
npx agentvibes install

# 2. Choose Piper TTS provider (recommended)
# Select: Piper > fr_FR-tom-medium > Light reverb > Low verbosity

# 3. Verify installation
ls -la .claude/hooks/play-tts.sh
ls -la ~/.claude/piper-voices/

Stuck? See Full Installation Guide or Troubleshooting

First Test

# Launch Claude Code
claude

# In Claude, test TTS
/agent-vibes:whoami
/agent-vibes:list
> "Say hello in French"

You should hear audio narration!

Activation & Deactivation

Quick Mute/Unmute

# In Claude Code
/agent-vibes:mute      # Mute (persists across sessions)
/agent-vibes:unmute    # Unmute

# Or manually
touch .claude/agentvibes-muted      # Project mute
touch ~/.agentvibes-muted           # Global mute
rm .claude/agentvibes-muted         # Project unmute

Mute Hierarchy

Priority 1: .claude/agentvibes-unmuted  (project override)
Priority 2: .claude/agentvibes-muted    (project mute)
Priority 3: ~/.agentvibes-muted         (global mute)
Priority 4: Active by default

Example: Mute globally, unmute specific project:

touch ~/.agentvibes-muted                 # All projects muted
touch .claude/agentvibes-unmuted          # This project unmuted

Complete Uninstall

# Automated uninstall
npx agentvibes uninstall --yes

# Manual cleanup (if needed)
rm -rf .claude/hooks/*vibes*
rm -rf .claude/commands/agent-vibes/
rm -rf .claude/audio/
rm -rf ~/.claude/piper-voices/
pipx uninstall piper-tts

Essential Commands

Provider Management

/agent-vibes:provider list              # List available providers
/agent-vibes:provider switch piper      # Switch to Piper TTS
/agent-vibes:provider switch macos      # Switch to macOS Say
/agent-vibes:provider info              # Current provider details

Voice Management

/agent-vibes:list                       # List all voices
/agent-vibes:list first 5               # Show first 5 voices
/agent-vibes:switch fr_FR-tom-medium    # Switch to French male voice
/agent-vibes:whoami                     # Current voice & provider
/agent-vibes:preview                    # Preview first 3 voices
/agent-vibes:sample fr_FR-tom-medium    # Test specific voice

Audio Control

/agent-vibes:mute                       # Mute all TTS
/agent-vibes:unmute                     # Unmute TTS
/agent-vibes:replay                     # Replay last audio
/agent-vibes:replay 2                   # Replay second-to-last
/agent-vibes:verbosity low              # Speak less (recommended)
/agent-vibes:verbosity medium           # Speak more

Effects & Personalization

/agent-vibes:effects reverb light       # Add light reverb
/agent-vibes:effects off                # Disable all effects
/agent-vibes:background-music on        # Enable background music
/agent-vibes:background-music off       # Disable background music
/agent-vibes:personality sarcastic      # Change personality
/agent-vibes:personality professional   # Professional mode

Utility Commands

/agent-vibes:hide                       # Hide all 34 commands
/agent-vibes:show                       # Show commands again
/agent-vibes:version                    # Agent Vibes version
/agent-vibes:update                     # Update Agent Vibes

Full command reference: 34 commands available. Use /agent-vibes:hide if they clutter your command palette.

Voice Catalog Quick Reference

French Voices (4 models, 128 speakers)

Voice	Gender	Quality	Speakers	Use Case
fr_FR-tom-medium	Male	Medium	1	⭐️⭐️⭐️⭐️⭐️ Best FR male
fr_FR-siwis-medium	Female	Medium	1	Clear, natural
fr_FR-upmc-medium	Neutral	Medium	1	Multi-purpose
fr_FR-mls-medium	Mixed	Medium	124	⭐️⭐️⭐️⭐️⭐️ Maximum variety

Multi-speakers: fr_FR-mls-medium has 124 different voices (49 female, 75 male). Use -s 0-123 flag to select specific speaker.

English Voices (12 models)

Voice	Gender	Quality	Character
en_US-ryan-high	Male	High	⭐️⭐️⭐️⭐️⭐️ Professional
en_US-amy-medium	Female	Medium	Warm, natural
en_US-lessac-medium	Male	Medium	Authoritative
en_US-libritts-high	Mixed	High	Very natural
...	...	...	8 more voices

Full catalog with audio samples: Voice Catalog

Common Use Cases

1. Listen During Code Reviews

# Enable TTS with low verbosity
/agent-vibes:verbosity low

# Work on other tasks while listening to Claude's analysis
> "Review the authentication middleware for security issues"

2. Audio Notifications for Long Tasks

# Run long test suite, get notified when done
> "Run the full test suite and report failures"
# → Audio alert when tests complete

3. Language Learning Mode

# Enable dual-language TTS
/agent-vibes:learn on
/agent-vibes:target es_ES
/agent-vibes:target-voice es_ES-davefx-medium

# Responses spoken in both English and Spanish
> "Explain dependency injection"

4. Custom Hooks (Errors Only)

# Create selective TTS hook
cat > .claude/hooks/speak-errors-only.sh << 'EOF'
#!/opt/homebrew/bin/bash
INPUT=$(cat)
BODY=$(echo "$INPUT" | jq -r '.notification.body // empty')

# Speak only if contains "error" or "failed"
if [[ "$BODY" =~ (error|failed|Error|Failed) ]]; then
  ~/.claude/hooks/play-tts.sh "$BODY"
fi
exit 0
EOF

chmod +x .claude/hooks/speak-errors-only.sh

Performance Tips

Reduce Latency

# Use low-quality voice (faster generation)
/agent-vibes:switch fr_FR-siwis-low  # If available

# Disable effects
/agent-vibes:effects off

# Disable background music
/agent-vibes:background-music off

# Result: ~150ms latency instead of ~280ms

Optimize for Battery

# macOS Say (instant, no CPU burst)
/agent-vibes:provider switch macos

# Trade-off: Lower quality, but 0ms generation time

Reduce Distraction

# Minimum verbosity
/agent-vibes:verbosity low

# Professional personality (less chatty)
/agent-vibes:personality professional

# Or mute during focus work
/agent-vibes:mute

Troubleshooting

No Audio

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

# 2. Verify 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

Solution: See Troubleshooting Guide for detailed diagnostics.

Voice Sounds Robotic

Solution: Switch to high-quality model:

# Download high-quality voice
cd ~/.claude/piper-voices
curl -L -o fr_FR-siwis-high.onnx \
  "https://huggingface.co/rhasspy/piper-voices/resolve/main/fr/fr_FR/siwis/high/fr_FR-siwis-high.onnx"

/agent-vibes:switch fr_FR-siwis-high

34 Commands Clutter Command Palette

Solution: Hide them:

/agent-vibes:hide

# Unhide later if needed
/agent-vibes:show

More issues? Check Troubleshooting Guide

Configuration Files

File	Purpose	Format
`.claude/tts-provider.txt`	Active provider	`piper` or `macos` or `termux`
`.claude/tts-voice.txt`	Active voice	`fr_FR-tom-medium`
`.claude/agentvibes-muted`	Project mute status	Existence = muted
`~/.agentvibes-muted`	Global mute status	Existence = muted
`.claude/config/audio-effects.cfg`	Audio effects config	Key=Value format
`~/.claude/piper-voices/*.onnx`	Voice models	Neural network models

Resources

GitHub: https://github.com/paulpreibisch/AgentVibes
Website: https://agentvibes.org
Demo Video: https://youtu.be/ngLiA_KQtTA
Piper Voices: https://huggingface.co/rhasspy/piper-voices
Piper Samples: https://rhasspy.github.io/piper-samples/

Contributing

Agent Vibes is a community project. Report issues or contribute:

Issues: https://github.com/paulpreibisch/AgentVibes/issues
License: Apache 2.0

Integration guide maintained by Claude Code Ultimate Guide Last updated: 2026-01-22 | Agent Vibes v3.0.0 | Piper TTS v1.3.0

FilesExpand file tree

README.md

Latest commit

History