marketing-shibata50/claude-code-ultimate-guide
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: add Agent Vibes TTS integration documentation (v3.11.1)

Browse source 
Added comprehensive documentation for text-to-speech integration via Agent Vibes MCP server.

New files (8):
- examples/integrations/agent-vibes/README.md - Quick start guide
- examples/integrations/agent-vibes/installation.md - 18-minute setup procedure
- examples/integrations/agent-vibes/voice-catalog.md - 15 voices (4 FR models, 128 speakers)
- examples/integrations/agent-vibes/troubleshooting.md - 7 common issues solved
- guide/workflows/tts-setup.md - Step-by-step workflow
- examples/hooks/bash/tts-selective.sh - Custom selective TTS hook
- examples/claude-md/tts-enabled.md - Project template

Documentation:
- guide/ai-ecosystem.md (section 5.1) - TTS tools overview
- guide/README.md - Added TTS workflow reference
- machine-readable/reference.yaml - 8 TTS entries

Version updates:
- VERSION: 3.11.0 → 3.11.1
- README.md: Template count 71 → 83
- CHANGELOG.md: Added v3.11.1 entry
- Synced version across all docs (cheatsheet, ultimate-guide, reference.yaml)

Other:
- .gitignore: Added audio file exclusions (*.wav, *.mp3, *.onnx)

Context: Tested Agent Vibes v3.0.0 + Piper TTS with French voices. Works offline, no cloud dependency.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Florian BRUNIAUX 2026-01-22 16:08:32 +01:00
parent 89f81562b5
commit 5fbea061d5
16 changed files with 2470 additions and 14 deletions
Download patch file Download diff file Expand all files Collapse all files

3
guide/README.md
View file

@ -17,7 +17,7 @@ Core documentation for mastering Claude Code.
| [methodologies.md](./methodologies.md) | 15 development methodologies reference (TDD, SDD, BDD, etc.) | 20 min |
| [security-hardening.md](./security-hardening.md) | Security threats, MCP vetting, injection defense | 25 min |
| [devops-sre.md](./devops-sre.md) | FIRE framework for infrastructure diagnosis and incident response | 30 min |
| [ai-ecosystem.md](./ai-ecosystem.md) | Complementary AI tools (Perplexity, Gemini, Kimi, NotebookLM) | 25 min |
| [ai-ecosystem.md](./ai-ecosystem.md) | Complementary AI tools (Perplexity, Gemini, Kimi, NotebookLM, TTS) | 30 min |
| [cowork.md](./cowork.md) | Claude Cowork: Summary (see [dedicated repo](https://github.com/FlorianBruniaux/claude-cowork-guide) for full docs) | 5 min |
| [workflows/](./workflows/) | Practical workflow guides for Claude Code | 30 min |
@ -44,6 +44,7 @@ Hands-on guides for effective development patterns:
| [workflows/spec-first.md](./workflows/spec-first.md) | Spec-First Development (SDD) |
| [workflows/plan-driven.md](./workflows/plan-driven.md) | Using /plan mode effectively |
| [workflows/iterative-refinement.md](./workflows/iterative-refinement.md) | Iterative improvement loops |
| [workflows/tts-setup.md](./workflows/tts-setup.md) | Add text-to-speech narration to Claude Code (18 min) |
## Recommended Reading Order

88
guide/ai-ecosystem.md
View file

@ -504,6 +504,94 @@ See `/voice-refine` skill template in `examples/skills/`.
---
## 5.1 Text-to-Speech Tools (Agent Vibes)
**Philosophy**: Audible narration frees your eyes for multitasking
Text-to-speech adds audio narration to Claude Code responses, enabling:
- **Code reviews while multitasking** (listen while reviewing diffs visually)
- **Long debugging sessions** (audio notifications keep you informed)
- **Accessibility** (visual impairment, eye strain, RSI)
- **Background monitoring** (alerts for errors/completion)
### Tool: Agent Vibes (Community MCP Server)
**Status**: Optional integration (not official Claude Code feature)
**Cost**: 100% free (offline TTS)
**Maintenance**: Community-driven (Paul Preibisch)
| Feature | Value |
|---------|-------|
| **Provider** | Piper TTS (offline neural) + macOS Say (native) |
| **Voices** | 15+ (12 English, 4 French including 124 multi-speakers) |
| **Quality** | ⭐️⭐️⭐️⭐️ (Piper medium), ⭐️⭐️⭐️⭐️⭐️ (Piper high) |
| **Latency** | ~280ms (Piper medium), ~50ms (macOS Say) |
| **Disk Space** | ~1.3GB (Piper + voices + audio effects) |
| **Installation** | ~18 minutes (5 phases, interactive) |
### When TTS Shines
| Scenario | Benefit |
|----------|---------|
| Code reviews | Listen to Claude's analysis while viewing code |
| Long-running tasks | Audio notification when tests/builds complete |
| Debugging sessions | Error alerts without constant screen checking |
| Learning mode | Dual-language narration (main + target language) |
| Pair programming | One person codes, both hear Claude's feedback |
### Trade-offs
| Advantage | Limitation |
|-----------|------------|
| 100% offline | No cloud-quality voices (vs ElevenLabs) |
| Zero cost | ~280ms latency (vs instant macOS Say) |
| Multi-language (50+) | ~1GB disk space for voice models |
| 124 voice variety | Installation requires Homebrew, Bash 5.x |
### Quick Start
**Installation**: [TTS Setup Workflow](./workflows/tts-setup.md) (18 min)
**Basic usage**:
```bash
# In Claude Code
/agent-vibes:whoami # Check current voice & provider
/agent-vibes:list # List all 15 voices
/agent-vibes:switch fr_FR-tom-medium # French male voice
# Test
> "Say hello in French" # Audio narration plays
```
**Mute temporarily**:
```bash
/agent-vibes:mute # Silent work
# ... focus time ...
/agent-vibes:unmute # Re-enable
```
### Recommendation
| Profile | Setup |
|---------|-------|
| **Code reviewer** | ✅ Install with `fr_FR-tom-medium`, `verbosity: low` |
| **Focus worker** | ⚠️ Install but mute by default, unmute for notifications |
| **Battery-conscious** | Use macOS Say provider (instant, lower quality) |
| **Public workspace** | ❌ Skip TTS (audio distraction to others) |
### Complete Documentation
- **[Agent Vibes Integration Guide](../examples/integrations/agent-vibes/README.md)** - Overview, commands, use cases
- **[Installation Guide](../examples/integrations/agent-vibes/installation.md)** - 18-minute setup procedure
- **[Voice Catalog](../examples/integrations/agent-vibes/voice-catalog.md)** - 15 voices with audio samples
- **[Troubleshooting](../examples/integrations/agent-vibes/troubleshooting.md)** - Common issues & solutions
**Resources**:
- GitHub: https://github.com/paulpreibisch/AgentVibes
- Voice Samples: https://rhasspy.github.io/piper-samples/
---
## 6. IDE-Based Tools (Cursor, Windsurf, Cline)
> **Technical Comparison**: For an objective comparison of Claude Code vs 22+ alternatives across 11 criteria (MCP support, Skills, Commands, Subagents, Plan Mode), see the [AI Coding Agents Matrix](https://coding-agents-matrix.dev/) (updated Jan 2026).

4
guide/cheatsheet.md
View file

@ -6,7 +6,7 @@
**Written with**: Claude (Anthropic)
**Version**: 3.11.0 | **Last Updated**: January 2026
**Version**: 3.11.1 | **Last Updated**: January 2026
---
@ -423,4 +423,4 @@ where.exe claude; claude doctor; claude mcp list
**Author**: Florian BRUNIAUX | [@Méthode Aristote](https://methode-aristote.fr) | Written with Claude
*Last updated: January 2026 | Version 3.11.0*
*Last updated: January 2026 | Version 3.11.1*

4
guide/ultimate-guide.md
View file

@ -10,7 +10,7 @@
**Last updated**: January 2026
**Version**: 3.11.0
**Version**: 3.11.1
---
@ -13616,4 +13616,4 @@ Thumbs.db
**Contributions**: Issues and PRs welcome.
**Last updated**: January 2026 | **Version**: 3.11.0
**Last updated**: January 2026 | **Version**: 3.11.1

338
guide/workflows/tts-setup.md Normal file
View file

@ -0,0 +1,338 @@
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# Install Piper TTS
pipx install piper-tts
# Verify
piper --help
# Expected: Piper usage instructions
# ✅ Checkpoint: Piper installed
```
### Step 3.2: Download French Voices
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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**:
```bash
/agent-vibes:verbosity low
/agent-vibes:effects off
```
**For focus work**:
```bash
/agent-vibes:mute # Mute temporarily
# Work without audio
/agent-vibes:unmute # Re-enable when done
```
**For battery optimization**:
```bash
# Switch to macOS Say (instant, no CPU burst)
/agent-vibes:provider switch macos
```
### Add to .gitignore
```bash
# 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](../../examples/integrations/agent-vibes/troubleshooting.md)
---
## Next Steps
- **[Voice Catalog](../../examples/integrations/agent-vibes/voice-catalog.md)** - Explore 15 voices
- **[Integration Guide](../../examples/integrations/agent-vibes/README.md)** - Learn commands
- **[Installation Details](../../examples/integrations/agent-vibes/installation.md)** - Deep dive
---
## Uninstall Instructions
To remove Agent Vibes completely:
```bash
# 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](https://github.com/FlorianBruniaux/claude-code-ultimate-guide)*
*Last updated: 2026-01-22 | Agent Vibes v3.0.0*