TTS Setup Workflow - Agent Vibes Installation

Goal: Add text-to-speech narration to Claude Code Time: 18 minutes Difficulty: Intermediate System: macOS (Homebrew required)

Decision Point: Should You Install TTS?

Use this quick assessment:

Question	Answer	Score
Do you work on long code reviews?	Yes	+2
Do you multitask during debugging?	Yes	+2
Do you prefer audio notifications?	Yes	+1
Do you need offline TTS (no cloud)?	Yes	+2
Is latency critical (<100ms required)?	Yes	-2
Do you work in public spaces (no audio)?	Yes	-3
Do you prefer silent work environment?	Yes	-2

Score:

≥3: Install TTS (good fit)
0-2: Optional (try it, can uninstall)
<0: Skip TTS (not a good fit)

Workflow Overview

Phase 1: Prerequisites (5 min)
    ↓
Phase 2: Agent Vibes Install (5 min)
    ↓
Phase 3: Piper TTS + Voices (5 min)
    ↓
Phase 4: Test & Configure (3 min)
    ↓
Phase 5: Verify (1 min)

Phase 1: Prerequisites (5 minutes)

Checkpoint 1.1: System Requirements

# Verify macOS version
sw_vers
# Required: macOS 10.15+

# Verify Homebrew
brew --version
# If missing: /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Verify Node.js
node --version
# Required: 16.0.0+

Checkpoint 1.2: Install Bash 5.x

# Install
brew install bash

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

# ✅ Checkpoint: Bash 5.x installed

Checkpoint 1.3: Install Dependencies

# Install audio tools
brew install sox ffmpeg util-linux espeak-ng

# Verify all installed
command -v sox && command -v ffmpeg && command -v espeak-ng && echo "✅ Dependencies OK"

# ✅ Checkpoint: Dependencies installed

Total time Phase 1: ~5 minutes

Phase 2: Agent Vibes Installation (5 minutes)

Step 2.1: Launch Installer

# Navigate to your project
cd /path/to/your/claude-project

# Launch interactive installer
npx agentvibes install

Expected: ASCII banner + 4-page interactive installer

Step 2.2: Navigate Pages

Page 1/4 - Dependencies:

Review: Should show all ✓ green checkmarks
Action: Click “Next →”

Page 2/4 - Provider:

Select: Piper TTS (best quality, offline)
Action: Click “Next →”

Page 3/4 - Voice:

French: Select fr_FR-tom-medium (male, professional)
English: Select en_US-ryan-high (best quality)
Action: Click “Next →”

Page 4/4 - Settings:

Reverb: Light (recommended)
Background Music: Disabled (avoid distraction)
Verbosity: Low (less chatty)
Action: Click “Start Installation”

Checkpoint 2.3: Verify Installation

# Check installed files
ls .claude/hooks/play-tts.sh
ls .claude/commands/agent-vibes/
cat .claude/tts-provider.txt
# Expected: Files exist, provider shows "macos" or "piper"

# ✅ Checkpoint: Agent Vibes installed

Total time Phase 2: ~5 minutes

Phase 3: Piper TTS + French Voices (5 minutes)

Step 3.1: Install Piper via pipx

# Install Piper TTS
pipx install piper-tts

# Verify
piper --help
# Expected: Piper usage instructions

# ✅ Checkpoint: Piper installed

Step 3.2: Download French Voices

# Create voice directory
mkdir -p ~/.claude/piper-voices
cd ~/.claude/piper-voices

# Download French male voice (recommended)
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"

# Download French female voice (optional)
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"

# ✅ Checkpoint: Voices downloaded (~120MB)

Total time Phase 3: ~5 minutes

Phase 4: Configuration & Testing (3 minutes)

Step 4.1: Configure Provider & Voice

# Set Piper as provider
echo "piper" > .claude/tts-provider.txt

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

# Verify configuration
cat .claude/tts-provider.txt  # Expected: piper
cat .claude/tts-voice.txt     # Expected: fr_FR-tom-medium

# ✅ Checkpoint: Configuration set

Step 4.2: Test Audio Pipeline

# Test Piper directly
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

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

# ✅ Checkpoint: Audio works

Expected: You should hear French male voice.

Total time Phase 4: ~3 minutes

Phase 5: Verification in Claude Code (1 minute)

Step 5.1: Launch & Test

# Start Claude Code
claude

# In Claude, run:
/agent-vibes:whoami
# Expected: Shows "piper" provider and "fr_FR-tom-medium" voice

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

# ✅ Checkpoint: TTS active in Claude Code

Step 5.2: Configure Preferences

# Reduce verbosity (recommended)
/agent-vibes:verbosity low

# Hide 34 commands if cluttered
/agent-vibes:hide

# ✅ Checkpoint: Preferences set

Total time Phase 5: ~1 minute

Total Time: ~18 Minutes ✅

Post-Setup Recommendations

Optimize for Your Workflow

For code reviews:

/agent-vibes:verbosity low
/agent-vibes:effects off

For focus work:

/agent-vibes:mute  # Mute temporarily
# Work without audio
/agent-vibes:unmute  # Re-enable when done

For battery optimization:

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

Add to .gitignore

# Prevent committing large audio files
echo ".claude/audio/" >> .gitignore
echo ".claude/piper-voices/" >> .gitignore
echo "*.wav" >> .gitignore
echo "*.onnx" >> .gitignore

Troubleshooting Quick Reference

Issue	Quick Fix
No audio	Check `cat .claude/tts-provider.txt`
Wrong voice	Run `/agent-vibes:switch fr_FR-tom-medium`
Too verbose	Run `/agent-vibes:verbosity low`
Commands clutter	Run `/agent-vibes:hide`

Full troubleshooting: Agent Vibes Troubleshooting

Next Steps

Voice Catalog - Explore 15 voices
Integration Guide - Learn commands
Installation Details - Deep dive

Uninstall Instructions

To remove Agent Vibes completely:

# 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

Workflow guide maintained by Claude Code Ultimate Guide Last updated: 2026-01-22 | Agent Vibes v3.0.0