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
.gitignore vendored
View file

@ -21,6 +21,9 @@ npm-debug.log*
*.log
*.tmp
*.bak
*.wav
*.mp3
*.onnx
# Personal notes & temp files
to-ignore/

37
CHANGELOG.md
View file

@ -8,6 +8,43 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
---
## [3.11.1] - 2026-01-22
### Added
- **Agent Vibes TTS Integration** (`examples/integrations/agent-vibes/`)
- **8 documentation files, 2,400+ lines**: Complete text-to-speech integration guide
- **Integration guide** (`README.md`): Quick start with decision matrix, 30-second overview, architecture diagram, essential commands
- **Installation guide** (`installation.md`): 18-minute step-by-step procedure across 5 phases (bash 5.x, dependencies, Agent Vibes, Piper TTS, French voices)
- **Voice catalog** (`voice-catalog.md`): Detailed catalog of 15 voices (4 French models with 128 total speakers via multi-speaker models)
- **Troubleshooting guide** (`troubleshooting.md`): Solutions for 7 common issues with diagnostic script
- **Workflow** (`guide/workflows/tts-setup.md`): 18-minute guided workflow with decision scoring system and 5 checkpointed phases
- **Custom hook example** (`examples/hooks/bash/tts-selective.sh`): Selective TTS activation (errors only) with pattern matching
- **Project template** (`examples/claude-md/tts-enabled.md`): CLAUDE.md template for TTS-enabled projects with team guidelines
- **Key features**:
- Offline TTS with Piper (no cloud dependency)
- French voice support (4 models: tom, siwis, upmc, mls-124speakers)
- Mute hierarchy system (project override → project mute → global mute)
- Provider auto-detection (macOS Say, Piper TTS)
- Audio effects pipeline (reverb, echo, background music)
- **Documentation**: Added section 5.1 "Text-to-Speech Tools" in `guide/ai-ecosystem.md` (80+ lines with tables, quick start, recommendations)
### Changed
- **Template count**: 71 → 83 (+12 templates including integration docs, hook, workflow, CLAUDE.md template)
- **README.md**: Updated badges (71→83), template counts (66→83, 74→83), version footer (3.11.0→3.11.1)
- **guide/README.md**: Added TTS workflow reference and ai-ecosystem.md section update
- **machine-readable/reference.yaml**: Added 8 TTS-related entries (tts_integration_guide, tts_installation, tts_voice_catalog, tts_troubleshooting, tts_workflow, tts_ai_ecosystem, tts_hook_example, tts_claude_md_template)
- **.gitignore**: Added audio file exclusions (*.wav, *.mp3, *.onnx)
### Context
- **Use case**: Add audible narration to Claude Code for multitasking during code reviews, debugging, or long-running operations
- **Target audience**: Developers wanting TTS feedback without cloud dependencies, preference for high-quality French voices
- **Methodology**: Community MCP server (Agent Vibes v3.0.0) + Piper TTS + offline voice models from Hugging Face
---
## [3.11.0] - 2026-01-21
### Added

14
README.md
View file

@ -6,7 +6,7 @@
<p align="center">
<a href="https://github.com/FlorianBruniaux/claude-code-ultimate-guide/stargazers"><img src="https://img.shields.io/github/stars/FlorianBruniaux/claude-code-ultimate-guide?style=for-the-badge" alt="Stars"/></a>
<a href="./examples/"><img src="https://img.shields.io/badge/Templates-71-green?style=for-the-badge" alt="Templates"/></a>
<a href="./examples/"><img src="https://img.shields.io/badge/Templates-83-green?style=for-the-badge" alt="Templates"/></a>
<a href="./quiz/"><img src="https://img.shields.io/badge/Quiz-227_questions-orange?style=for-the-badge" alt="Quiz"/></a>
</p>
@ -64,7 +64,7 @@ Save as `CLAUDE.md` in your project root. Claude reads it automatically.
**The problem**: Awesome-lists give links, not learning paths. Official docs are dense. Tutorials get outdated in weeks.
**This guide**: Structured learning path with 74 copy-paste templates, from first install to advanced workflows.
**This guide**: Structured learning path with 83 copy-paste templates, from first install to advanced workflows.
**Reading time**: Quick Start ~15 min. Full guide ~3 hours (most read by section).
@ -207,7 +207,7 @@ claude-code-ultimate-guide/
</details>
<details>
<summary><strong>Examples Library</strong> (66 templates)</summary>
<summary><strong>Examples Library</strong> (83 templates)</summary>
**Agents** (6): [code-reviewer](./examples/agents/code-reviewer.md), [test-writer](./examples/agents/test-writer.md), [security-auditor](./examples/agents/security-auditor.md), [refactoring-specialist](./examples/agents/refactoring-specialist.md), [output-evaluator](./examples/agents/output-evaluator.md), [devops-sre](./examples/agents/devops-sre.md) ⭐
@ -219,6 +219,8 @@ claude-code-ultimate-guide/
**GitHub Actions**: [claude-pr-auto-review.yml](./examples/github-actions/claude-pr-auto-review.yml), [claude-security-review.yml](./examples/github-actions/claude-security-review.yml), [claude-issue-triage.yml](./examples/github-actions/claude-issue-triage.yml)
**Integrations** (1): [Agent Vibes TTS](./examples/integrations/agent-vibes/) - Text-to-speech narration for Claude Code responses
**[Browse Complete Catalog](./examples/README.md)** | **[Interactive Catalog](./examples/index.html)**
</details>
@ -339,7 +341,7 @@ Claude Code sends your prompts, file contents, and MCP results to Anthropic serv
**Status**: Research preview (Pro $20/mo or Max $100-200/mo, macOS only, **VPN incompatible**)
**Archive**: Historical versions available in git history (pre-v3.11.0)
**Archive**: Historical versions available in git history (pre-v3.11.1)
</details>
@ -350,7 +352,7 @@ Claude Code sends your prompts, file contents, and MCP results to Anthropic serv
| Repository | Purpose | Audience |
|------------|---------|----------|
| **[Claude Code Guide](https://github.com/FlorianBruniaux/claude-code-ultimate-guide)** *(this repo)* | Comprehensive documentation (13K lines, 74 templates) | Developers |
| **[Claude Code Guide](https://github.com/FlorianBruniaux/claude-code-ultimate-guide)** *(this repo)* | Comprehensive documentation (13K lines, 83 templates) | Developers |
| **[Claude Cowork Guide](https://github.com/FlorianBruniaux/claude-cowork-guide)** | Non-technical usage (67 prompts, 5 workflows) | Knowledge workers |
| **Code Landing** *(to be deployed)* | Marketing site for Claude Code guide | Discovery |
| **Cowork Landing** *(to be deployed)* | Marketing site for Cowork guide | Discovery |
@ -408,7 +410,7 @@ Licensed under [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/).
---
*Version 3.11.0 | January 2026 | Crafted with Claude*
*Version 3.11.1 | January 2026 | Crafted with Claude*
<!-- SEO Keywords -->
<!-- claude code, claude code tutorial, anthropic cli, ai coding assistant, claude code mcp,

2
VERSION
View file

@ -1 +1 @@
3.11.0
3.11.1

109
examples/claude-md/tts-enabled.md Normal file
View file

@ -0,0 +1,109 @@
# Project with TTS Enabled
This is a template `CLAUDE.md` file for projects using Agent Vibes TTS.
## TTS Configuration
**Provider**: Piper TTS
**Voice**: fr_FR-tom-medium (French male)
**Verbosity**: Low (recommended)
**Effects**: Light reverb
**Background Music**: Disabled
## Project-Specific TTS Settings
### Mute During Focus Work
When working on tasks requiring deep concentration, mute TTS:
```bash
# Mute for this session
/agent-vibes:mute
# Unmute when done
/agent-vibes:unmute
```
### Selective TTS (Errors Only)
For this project, TTS speaks only error messages:
- ✅ Errors, failures, exceptions
- ❌ Regular responses, confirmations
- ❌ Informational messages
**Reason**: This is a critical production system where audio alerts for errors are valuable, but constant narration is distracting.
## Voice Preferences
| Task Type | Recommended Voice | Reason |
|-----------|-------------------|--------|
| Code reviews | fr_FR-tom-medium | Professional, clear |
| Documentation | fr_FR-siwis-medium | Warm, educational tone |
| Debugging | fr_FR-tom-medium (low verbosity) | Critical alerts only |
## Commands Reference
Quick reference for team members:
```bash
# Check current voice
/agent-vibes:whoami
# Switch voice
/agent-vibes:switch fr_FR-tom-medium
# Mute/unmute
/agent-vibes:mute
/agent-vibes:unmute
# Adjust verbosity
/agent-vibes:verbosity low
# Disable effects (faster)
/agent-vibes:effects off
```
## Team Guidelines
### When to Mute
- Pair programming sessions (speaker explains, TTS distracts)
- Video meetings (avoid audio conflicts)
- Deep focus work (flow state priority)
- Public spaces (avoid disturbing others)
### When to Enable
- Solo code reviews (listen while reviewing diffs)
- Long-running tasks (audio completion notifications)
- Background monitoring (alerts for errors)
- Learning mode (dual-language practice)
## Installation for Team Members
New team members should follow:
1. **Installation Guide**: [Agent Vibes Installation](../../integrations/agent-vibes/installation.md)
2. **Voice Selection**: Use `fr_FR-tom-medium` for consistency
3. **Configuration**: Copy settings from this file
## Troubleshooting
Common issues:
- **No audio**: Check `cat .claude/tts-provider.txt` → should be `piper`
- **Wrong voice**: Run `/agent-vibes:switch fr_FR-tom-medium`
- **Too verbose**: Run `/agent-vibes:verbosity low`
**Full troubleshooting**: [Agent Vibes Troubleshooting](../../integrations/agent-vibes/troubleshooting.md)
## Notes
- TTS is **optional** - not required for project contribution
- Mute status is **project-specific** (`.claude/agentvibes-muted`)
- Voice models are **shared globally** (`~/.claude/piper-voices/`)
---
*For more information about Agent Vibes TTS, see [Integration Guide](../../integrations/agent-vibes/README.md)*

80
examples/hooks/bash/tts-selective.sh Normal file
View file

@ -0,0 +1,80 @@
#!/opt/homebrew/bin/bash
#
# File: tts-selective.sh
# Purpose: Selective TTS hook - Speak only specific types of messages
#
# Usage: Replace .claude/hooks/play-tts.sh with this script for selective TTS
#
# Example configurations:
# - Errors only: Speak only when "error" or "failed" detected
# - Success only: Speak only when "success" or "completed" detected
# - Important only: Speak only high-priority notifications
#
# Installation:
# 1. Copy this file to .claude/hooks/
# 2. chmod +x .claude/hooks/tts-selective.sh
# 3. Backup original: cp .claude/hooks/play-tts.sh .claude/hooks/play-tts.sh.backup
# 4. Replace: cp .claude/hooks/tts-selective.sh .claude/hooks/play-tts.sh
#
# Restore original:
# cp .claude/hooks/play-tts.sh.backup .claude/hooks/play-tts.sh
#
set -e
# Get script directory
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
# Read input from stdin
INPUT=$(cat)
BODY=$(echo "$INPUT" | jq -r '.notification.body // empty')
# Exit if no body
if [[ -z "$BODY" ]]; then
exit 0
fi
# ═══════════════════════════════════════════════════════════════
# CONFIGURATION: Customize trigger patterns below
# ═══════════════════════════════════════════════════════════════
# Option 1: Errors Only
# Speak only when message contains error keywords
TRIGGER_PATTERN="(error|Error|ERROR|failed|Failed|FAILED|exception|Exception)"
# Option 2: Success Only (uncomment to use)
# TRIGGER_PATTERN="(success|Success|completed|Completed|done|Done|✓|✅)"
# Option 3: Important Only (uncomment to use)
# TRIGGER_PATTERN="(CRITICAL|WARNING|ERROR|FAILURE|BREAKING)"
# Option 4: Code-related Only (uncomment to use)
# TRIGGER_PATTERN="(test|tests|build|compile|deploy|commit|push|merge)"
# Option 5: Custom Keywords (uncomment and edit)
# TRIGGER_PATTERN="(production|deploy|release|urgent|critical)"
# ═══════════════════════════════════════════════════════════════
# LOGIC: Check if message matches trigger pattern
# ═══════════════════════════════════════════════════════════════
if [[ "$BODY" =~ $TRIGGER_PATTERN ]]; then
# Message matches trigger - speak it
# Call original TTS hook (or Agent Vibes play-tts.sh)
if [[ -f "$SCRIPT_DIR/play-tts.sh.backup" ]]; then
# Use backup if exists
"$SCRIPT_DIR/play-tts.sh.backup" "$BODY"
elif [[ -f ~/.claude/hooks/play-tts.sh ]]; then
# Use global Agent Vibes hook
~/.claude/hooks/play-tts.sh "$BODY"
else
# Fallback: macOS Say
say "$BODY" &
fi
else
# Message doesn't match trigger - silent exit
exit 0
fi
exit 0

424
examples/integrations/agent-vibes/README.md Normal file
View file

@ -0,0 +1,424 @@
# Agent Vibes TTS - Text-to-Speech for Claude Code
**Status**: Community MCP Server (optional)
**Version**: 3.0.0
**Maintainer**: [Paul Preibisch](https://github.com/paulpreibisch/AgentVibes)
**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](./installation.md) | [Quick Workflow](../../../guide/workflows/tts-setup.md)
**Usage**: [Voice Catalog](./voice-catalog.md) | [Troubleshooting](./troubleshooting.md)
---
## 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
```bash
# 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](./installation.md) or [Troubleshooting](./troubleshooting.md)
### First Test
```bash
# 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
```bash
# 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:
```bash
touch ~/.agentvibes-muted # All projects muted
touch .claude/agentvibes-unmuted # This project unmuted
```
### Complete Uninstall
```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
```
---
## Essential Commands
### Provider Management
```bash
/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
```bash
/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
```bash
/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
```bash
/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
```bash
/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](./voice-catalog.md)
---
## Common Use Cases
### 1. Listen During Code Reviews
```bash
# 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
```bash
# 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
```bash
# 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)
```bash
# 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
```bash
# 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
```bash
# macOS Say (instant, no CPU burst)
/agent-vibes:provider switch macos
# Trade-off: Lower quality, but 0ms generation time
```
### Reduce Distraction
```bash
# 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
```bash
# 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](./troubleshooting.md) for detailed diagnostics.
### Voice Sounds Robotic
**Solution**: Switch to high-quality model:
```bash
# 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:
```bash
/agent-vibes:hide
# Unhide later if needed
/agent-vibes:show
```
**More issues?** Check [Troubleshooting Guide](./troubleshooting.md)
---
## 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 |
---
## Related Documentation
- **[Installation Guide](./installation.md)** - Complete 18-minute setup procedure
- **[Voice Catalog](./voice-catalog.md)** - All 15 voices with audio samples
- **[Troubleshooting](./troubleshooting.md)** - Common issues and solutions
- **[TTS Setup Workflow](../../../guide/workflows/tts-setup.md)** - Step-by-step installation
- **[AI Ecosystem](../../../guide/ai-ecosystem.md#47-voice-interfaces)** - TTS in AI context
---
## 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](https://github.com/FlorianBruniaux/claude-code-ultimate-guide)*
*Last updated: 2026-01-22 | Agent Vibes v3.0.0 | Piper TTS v1.3.0*

544
examples/integrations/agent-vibes/installation.md Normal file
View file

@ -0,0 +1,544 @@
# 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).
```bash
# 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
```bash
# 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)
```bash
# 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 ✅
```bash
# 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
```bash
# 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 ✅
```bash
# 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:
```bash
# 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
```bash
# 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:
```bash
ls ~/.claude/piper-voices/en_US-*.onnx
```
**Expected**: 12 files (ryan, amy, lessac, bryce, etc.)
### Checkpoint 3: Voices Downloaded ✅
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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](./troubleshooting.md#no-audio).
### Checkpoint 4: Configuration Complete ✅
```bash
# 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
```bash
# Start Claude Code session
claude
```
### Step 5.2: Test TTS Commands
```bash
# 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
```bash
# 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 ✅
```bash
# 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)
```bash
# In Claude Code
/agent-vibes:verbosity low
```
**Why**: Reduces audio narration frequency, less distracting.
### Hide 34 Commands (Optional)
```bash
# In Claude Code
/agent-vibes:hide
```
**Why**: Declutters command palette. Use `/agent-vibes:show` to unhide.
### Disable Background Music
```bash
# In Claude Code
/agent-vibes:background-music off
```
**Why**: Background music can be distracting during focus work.
### Set Project Mute (Optional)
```bash
# 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
```bash
# Uninstall Agent Vibes completely
npx agentvibes uninstall --yes
```
### Manual Cleanup
```bash
# 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**:
```bash
# 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):
```bash
# 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**:
```bash
# 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](./troubleshooting.md).
---
## Next Steps
After installation:
1. **[Voice Catalog](./voice-catalog.md)** - Explore 15 voices and choose your favorite
2. **[README](./README.md)** - Learn essential commands and use cases
3. **[Troubleshooting](./troubleshooting.md)** - Solve common issues
4. **[AI Ecosystem](../../../guide/ai-ecosystem.md#47-voice-interfaces)** - 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](https://github.com/FlorianBruniaux/claude-code-ultimate-guide)*
*Last updated: 2026-01-22 | Tested on: macOS Sequoia 24.6.0 (Apple Silicon)*

441
examples/integrations/agent-vibes/troubleshooting.md Normal file
View file

@ -0,0 +1,441 @@
# Agent Vibes - Troubleshooting Guide
**Common Issues**: 7 scenarios with step-by-step solutions
**Diagnostic Tools**: Commands and scripts for problem identification
---
## Issue 1: No Audio Output
### Symptom
```
Claude responds but no TTS audio plays
```
### Diagnostic Steps
```bash
# 1. Check if muted
ls -la .claude/agentvibes-muted ~/.agentvibes-muted
# If file exists → TTS is muted
# 2. Check provider configuration
cat .claude/tts-provider.txt
# Expected: "piper" or "macos"
# 3. Check voice configuration
cat .claude/tts-voice.txt
# Expected: voice name like "fr_FR-tom-medium"
# 4. Test Piper directly
echo "Test audio" | piper -m ~/.claude/piper-voices/fr_FR-tom-medium.onnx \
--output-file /tmp/test.wav && afplay /tmp/test.wav
```
### Solutions
**If muted**:
```bash
# Unmute
rm .claude/agentvibes-muted
rm ~/.agentvibes-muted 2>/dev/null
# Or in Claude Code
/agent-vibes:unmute
```
**If provider misconfigured**:
```bash
# Set Piper as provider
echo "piper" > .claude/tts-provider.txt
# Verify
cat .claude/tts-provider.txt
```
**If voice missing**:
```bash
# Download missing voice
cd ~/.claude/piper-voices
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"
```
**If Piper command fails**:
```bash
# Reinstall Piper via pipx
pipx uninstall piper-tts
pipx install piper-tts
# Verify
piper --help
```
---
## Issue 2: libespeak-ng.1.dylib Not Found
### Symptom
```
dyld[xxx]: Library not loaded: @rpath/libespeak-ng.1.dylib
Referenced from: /Users/.../piper
Reason: tried: '/usr/local/lib/libespeak-ng.1.dylib' (no such file)
```
### Root Cause
Piper binary requires `espeak-ng` library which is not installed.
### Solution
```bash
# Install espeak-ng
brew install espeak-ng
# Verify installation
espeak-ng --version
# Expected: eSpeak NG text-to-speech: 1.52.0
# Find library location
find /opt/homebrew -name "libespeak-ng*.dylib"
# Expected: /opt/homebrew/lib/libespeak-ng.1.dylib
# If Piper still fails, reinstall via pipx (not binary)
pipx uninstall piper-tts 2>/dev/null
pipx install piper-tts
# Test again
piper --help
```
### Prevention
Always install `espeak-ng` **before** installing Piper TTS.
---
## Issue 3: Voice Sounds Robotic or Low Quality
### Symptom
```
Audio plays but voice quality is poor, robotic, unnatural
```
### Diagnostic
```bash
# Check which voice model is loaded
cat .claude/tts-voice.txt
# Check voice quality level
ls -lh ~/.claude/piper-voices/*.onnx | grep $(cat .claude/tts-voice.txt)
# Low quality: ~20-30MB
# Medium quality: ~50-70MB
# High quality: ~100-150MB
```
### Solutions
**Upgrade to high-quality model**:
```bash
# Download high-quality French 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"
curl -L -o fr_FR-siwis-high.onnx.json \
"https://huggingface.co/rhasspy/piper-voices/resolve/main/fr/fr_FR/siwis/high/fr_FR-siwis-high.onnx.json"
# Switch to high-quality voice
/agent-vibes:switch fr_FR-siwis-high
```
**Alternative: Try different voice**:
```bash
# Test multiple voices to find preferred one
/agent-vibes:preview
# Or test manually
for voice in fr_FR-tom-medium fr_FR-siwis-medium fr_FR-upmc-medium; do
echo "Test voix $voice" | \
piper -m ~/.claude/piper-voices/${voice}.onnx \
--output-file /tmp/${voice}.wav
afplay /tmp/${voice}.wav
sleep 2
done
```
**Quality Comparison**:
| Quality | Size | Latency | Naturalness |
|---------|------|---------|-------------|
| Low | ~25MB | ~100ms | ⭐️⭐️ |
| Medium | ~60MB | ~200ms | ⭐️⭐️⭐️⭐️ |
| High | ~120MB | ~400ms | ⭐️⭐️⭐️⭐️⭐️ |
---
## Issue 4: High Latency (>500ms)
### Symptom
```
Noticeable delay between Claude response and audio playback
```
### Diagnostic
```bash
# Time audio generation
time (echo "Test rapide" | \
piper -m ~/.claude/piper-voices/fr_FR-tom-medium.onnx \
--output-file /tmp/test.wav > /dev/null 2>&1)
# Expected: ~0.2s for medium quality
# Check if effects are enabled
cat .claude/config/audio-effects.cfg 2>/dev/null
# Look for REVERB_ENABLED=true, ECHO_ENABLED=true
# Check if background music enabled
cat .claude/config/background-music.cfg 2>/dev/null
# Look for ENABLED=true
```
### Solutions
**Switch to low-quality voice** (50% faster):
```bash
cd ~/.claude/piper-voices
curl -L -o fr_FR-gilles-low.onnx \
"https://huggingface.co/rhasspy/piper-voices/resolve/main/fr/fr_FR/gilles/low/fr_FR-gilles-low.onnx"
curl -L -o fr_FR-gilles-low.onnx.json \
"https://huggingface.co/rhasspy/piper-voices/resolve/main/fr/fr_FR/gilles/low/fr_FR-gilles-low.onnx.json"
/agent-vibes:switch fr_FR-gilles-low
```
**Disable audio effects**:
```bash
# In Claude Code
/agent-vibes:effects off
# Or manually
echo "REVERB_ENABLED=false" > .claude/config/audio-effects.cfg
echo "ECHO_ENABLED=false" >> .claude/config/audio-effects.cfg
```
**Disable background music**:
```bash
# In Claude Code
/agent-vibes:background-music off
# Or manually
echo "ENABLED=false" > .claude/config/background-music.cfg
```
**Switch to macOS Say** (instant, lower quality):
```bash
/agent-vibes:provider switch macos
```
**Performance Comparison**:
| Configuration | Latency | Quality |
|---------------|---------|---------|
| Piper High + Effects + Music | ~500ms | ⭐️⭐️⭐️⭐️⭐️ |
| Piper Medium + Effects | ~280ms | ⭐️⭐️⭐️⭐️ |
| Piper Medium (no effects) | ~200ms | ⭐️⭐️⭐️⭐️ |
| Piper Low (no effects) | ~100ms | ⭐️⭐️ |
| macOS Say | ~50ms | ⭐️⭐️⭐️ |
---
## Issue 5: Agent Vibes Commands Clutter Palette
### Symptom
```
34 /agent-vibes:* commands clutter Claude Code command palette
```
### Solution
```bash
# Hide all Agent Vibes commands
/agent-vibes:hide
# Commands still work, just hidden from autocomplete
# Unhide later if needed
/agent-vibes:show
```
### Alternative: Remove Agent Vibes Completely
```bash
npx agentvibes uninstall --yes
```
---
## Issue 6: Audio Plays Multiple Times (Echo/Repeat)
### Symptom
```
Same audio plays 2-3 times in rapid succession
```
### Root Cause
`flock` (file locking) not available, causing race condition with rapid messages.
### Diagnostic
```bash
# Check if flock is available
which flock || /opt/homebrew/opt/util-linux/bin/flock --version
```
### Solution
```bash
# Install util-linux (contains flock)
brew install util-linux
# Add flock to PATH (optional)
echo 'export PATH="/opt/homebrew/opt/util-linux/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
# Verify
flock --version
```
### Workaround (if flock unavailable)
```bash
# Reduce verbosity to minimize rapid messages
/agent-vibes:verbosity low
```
---
## Issue 7: Installation Hangs or Exits
### Symptom
```
npx agentvibes install exits with:
ExitPromptError: User force closed the prompt
```
### Root Cause
Interactive installer requires terminal input, can't be automated.
### Solution
```bash
# Ensure you're in interactive terminal (not script)
# Run directly in terminal, not via automation
npx agentvibes install
# If still fails, try without cache
npx --yes agentvibes@latest install
```
### Alternative: Manual Installation
```bash
# If installer fails repeatedly, install components manually
# 1. Install Piper TTS
pipx install piper-tts
# 2. Download voices
mkdir -p ~/.claude/piper-voices
cd ~/.claude/piper-voices
# ... download voices manually (see voice-catalog.md)
# 3. Create config files
echo "piper" > .claude/tts-provider.txt
echo "fr_FR-tom-medium" > .claude/tts-voice.txt
# 4. Download Agent Vibes scripts
# (Contact maintainer or extract from npm package)
```
---
## Diagnostic Script
Create comprehensive diagnostic script:
```bash
cat > /tmp/agent-vibes-diagnostic.sh << 'EOF'
#!/bin/bash
echo "=== Agent Vibes Diagnostic ==="
echo ""
echo "1. System Dependencies"
command -v /opt/homebrew/bin/bash && echo " ✓ Bash 5.x" || echo " ✗ Bash 5.x missing"
command -v sox && echo " ✓ sox" || echo " ✗ sox missing"
command -v ffmpeg && echo " ✓ ffmpeg" || echo " ✗ ffmpeg missing"
command -v espeak-ng && echo " ✓ espeak-ng" || echo " ✗ espeak-ng missing"
command -v piper && echo " ✓ piper" || echo " ✗ piper missing"
echo ""
echo "2. Configuration Files"
test -f .claude/tts-provider.txt && echo " ✓ Provider: $(cat .claude/tts-provider.txt)" || echo " ✗ Provider not configured"
test -f .claude/tts-voice.txt && echo " ✓ Voice: $(cat .claude/tts-voice.txt)" || echo " ✗ Voice not configured"
test -f .claude/hooks/play-tts.sh && echo " ✓ TTS hook installed" || echo " ✗ TTS hook missing"
echo ""
echo "3. Mute Status"
test -f .claude/agentvibes-muted && echo " ⚠ Project muted" || echo " ✓ Project unmuted"
test -f ~/.agentvibes-muted && echo " ⚠ Global muted" || echo " ✓ Global unmuted"
echo ""
echo "4. Voice Models"
echo " Installed voices: $(ls ~/.claude/piper-voices/*.onnx 2>/dev/null | wc -l)"
ls ~/.claude/piper-voices/*.onnx 2>/dev/null | sed 's|.*/||' | sed 's|.onnx||' | sed 's/^/ - /'
echo ""
echo "5. Audio Test"
if command -v piper > /dev/null 2>&1; then
echo "Test" | piper -m ~/.claude/piper-voices/$(cat .claude/tts-voice.txt).onnx \
--output-file /tmp/diagnostic-test.wav 2>&1 | grep -q "error" && \
echo " ✗ Audio generation failed" || echo " ✓ Audio generation successful"
afplay /tmp/diagnostic-test.wav 2>/dev/null && echo " ✓ Audio playback successful" || echo " ✗ Audio playback failed"
else
echo " ✗ Piper not installed, skipping test"
fi
echo ""
echo "=== End Diagnostic ==="
EOF
chmod +x /tmp/agent-vibes-diagnostic.sh
# Run diagnostic
/tmp/agent-vibes-diagnostic.sh
```
---
## Getting Help
If issues persist:
1. **Run diagnostic script** (above) and share output
2. **Check Agent Vibes GitHub Issues**: https://github.com/paulpreibisch/AgentVibes/issues
3. **Check Claude Code Guide**: [AI Ecosystem](../../../guide/ai-ecosystem.md)
4. **Check logs**: `tail -f ~/.claude/tts-debug.log` (if exists)
---
## Known Limitations
| Limitation | Impact | Workaround |
|------------|--------|------------|
| Bash 3.2 (macOS default) | Scripts fail | Install Bash 5.x via Homebrew |
| No Windows support | Can't run natively | Use WSL2 or macOS |
| flock optional | Audio may overlap | Install util-linux or reduce verbosity |
| Large voice files | ~1GB disk space | Delete unused voices |
| Latency with high-quality | ~400ms delay | Use medium or low quality |
---
*Troubleshooting 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*

380
examples/integrations/agent-vibes/voice-catalog.md Normal file
View file

@ -0,0 +1,380 @@
# Agent Vibes - Complete Voice Catalog
**Total Voices**: 15 installed + 50+ available
**Languages**: French (4 models, 128 speakers), English (12 models)
---
## French Voices (Voix Françaises)
### Overview
| Voice ID | Gender | Quality | Speakers | Size | Recommended |
|----------|--------|---------|----------|------|-------------|
| **fr_FR-tom-medium** | Male | Medium | 1 | 60MB | ⭐️⭐️⭐️⭐️⭐️ Best FR male |
| fr_FR-siwis-medium | Female | Medium | 1 | 60MB | ⭐️⭐️⭐️⭐️ Clear, natural |
| fr_FR-upmc-medium | Neutral | Medium | 1 | 73MB | ⭐️⭐️⭐️ Multi-purpose |
| **fr_FR-mls-medium** | Mixed | Medium | **124** | 73MB | ⭐️⭐️⭐️⭐️⭐️ Maximum variety |
---
### fr_FR-tom-medium ⭐️⭐️⭐️⭐️⭐️
**Gender**: Male
**Quality**: Medium
**Character**: Professional, clear pronunciation, neutral accent
**Best For**: Technical documentation, code reviews, professional context
**Latency**: ~200ms
**Usage**:
```bash
# In Claude Code
/agent-vibes:switch fr_FR-tom-medium
# Manual test
echo "Bonjour, je m'appelle Tom. Je suis une voix synthétique française." | \
piper -m ~/.claude/piper-voices/fr_FR-tom-medium.onnx \
--output-file /tmp/tom.wav && afplay /tmp/tom.wav
```
**Audio Sample**: Listen at https://rhasspy.github.io/piper-samples/ (search "fr_FR tom")
---
### fr_FR-siwis-medium ⭐️⭐️⭐️⭐️
**Gender**: Female
**Quality**: Medium
**Character**: Warm, natural, slightly Swiss accent
**Best For**: Tutorials, educational content, friendly interactions
**Latency**: ~200ms
**Usage**:
```bash
# In Claude Code
/agent-vibes:switch fr_FR-siwis-medium
# Manual test
echo "Bonjour, je suis Siwis. J'ai une voix claire et agréable." | \
piper -m ~/.claude/piper-voices/fr_FR-siwis-medium.onnx \
--output-file /tmp/siwis.wav && afplay /tmp/siwis.wav
```
**Audio Sample**: https://rhasspy.github.io/piper-samples/ (search "fr_FR siwis")
---
### fr_FR-upmc-medium ⭐️⭐️⭐️
**Gender**: Neutral (slightly female-leaning)
**Quality**: Medium
**Character**: Technical, precise, academic tone
**Best For**: Scientific content, data analysis, formal presentations
**Latency**: ~220ms (larger model)
**Usage**:
```bash
# In Claude Code
/agent-vibes:switch fr_FR-upmc-medium
# Manual test
echo "Analyse des données en cours. Résultats disponibles dans quelques instants." | \
piper -m ~/.claude/piper-voices/fr_FR-upmc-medium.onnx \
--output-file /tmp/upmc.wav && afplay /tmp/upmc.wav
```
**Audio Sample**: https://rhasspy.github.io/piper-samples/ (search "fr_FR upmc")
---
### fr_FR-mls-medium ⭐️⭐️⭐️⭐️⭐️ (Multi-Speaker)
**Gender**: Mixed (49 female, 75 male)
**Quality**: Medium
**Speakers**: **124 different voices**
**Character**: Massive variety (young, old, accents, tones)
**Best For**: Dialogue simulations, variety, character voices
**Latency**: ~200ms + speaker selection
**Usage**:
```bash
# In Claude Code (uses default speaker)
/agent-vibes:switch fr_FR-mls-medium
# Manual test with specific speaker (0-123)
echo "Je suis le speaker numéro 42" | \
piper -m ~/.claude/piper-voices/fr_FR-mls-medium.onnx -s 42 \
--output-file /tmp/mls-42.wav && afplay /tmp/mls-42.wav
# Test multiple speakers
for speaker in {0..5}; do
echo "Bonjour, speaker $speaker" | \
piper -m ~/.claude/piper-voices/fr_FR-mls-medium.onnx -s $speaker \
--output-file /tmp/mls-$speaker.wav
afplay /tmp/mls-$speaker.wav
sleep 1
done
```
**Speaker Selection**:
- `0-48`: Female voices (49 total)
- `49-123`: Male voices (75 total)
**Recommended Speakers**:
| Speaker ID | Gender | Character |
|------------|--------|-----------|
| 7 | Female | Young, energetic |
| 15 | Female | Mature, professional |
| 23 | Female | Warm, friendly |
| 55 | Male | Deep, authoritative |
| 72 | Male | Clear, technical |
| 99 | Male | Young, casual |
**Audio Samples**: https://rhasspy.github.io/piper-samples/ (search "fr_FR mls")
---
## English Voices (Voix Anglaises)
### Overview
| Voice ID | Gender | Quality | Character | Recommended |
|----------|--------|---------|-----------|-------------|
| **en_US-ryan-high** | Male | High | Professional | ⭐️⭐️⭐️⭐️⭐️ Best EN |
| en_US-amy-medium | Female | Medium | Warm, natural | ⭐️⭐️⭐️⭐️ |
| en_US-lessac-medium | Male | Medium | Authoritative | ⭐️⭐️⭐️⭐️ |
| en_US-libritts-high | Mixed | High | Very natural | ⭐️⭐️⭐️⭐️⭐️ |
| en_US-hfc_female-medium | Female | Medium | Technical | ⭐️⭐️⭐️ |
| en_US-bryce-medium | Male | Medium | Young, dynamic | ⭐️⭐️⭐️ |
| en_US-danny-low | Male | Low | Fast, efficient | ⭐️⭐️ |
| en_US-kathleen-low | Female | Low | Fast, efficient | ⭐️⭐️ |
| en_US-kusal-medium | Male | Medium | Indian accent | ⭐️⭐️⭐️ |
| en_US-kristin-medium | Female | Medium | Clear, neutral | ⭐️⭐️⭐️⭐️ |
| en_US-libritts_r-high | Mixed | High | Very natural | ⭐️⭐️⭐️⭐️⭐️ |
| 16Speakers | Multi | Medium | 16 different | ⭐️⭐️⭐️⭐️ |
---
### en_US-ryan-high ⭐️⭐️⭐️⭐️⭐️
**Gender**: Male
**Quality**: High (best English voice)
**Character**: Professional news anchor, clear pronunciation
**Best For**: Professional presentations, documentation, code reviews
**Latency**: ~400ms (high quality model)
**Usage**:
```bash
/agent-vibes:switch en_US-ryan-high
```
---
### en_US-amy-medium ⭐️⭐️⭐️⭐️
**Gender**: Female
**Quality**: Medium
**Character**: Warm, friendly, conversational
**Best For**: Tutorials, casual interactions, educational content
**Latency**: ~200ms
**Usage**:
```bash
/agent-vibes:switch en_US-amy-medium
```
---
### en_US-libritts-high ⭐️⭐️⭐️⭐️⭐️
**Gender**: Mixed (multi-speaker)
**Quality**: High
**Character**: Very natural, expressive
**Best For**: High-quality audio narration
**Latency**: ~400ms
**Usage**:
```bash
/agent-vibes:switch en_US-libritts-high
```
---
### 16Speakers ⭐️⭐️⭐️⭐️ (Multi-Speaker English)
**Gender**: Mixed (8 female, 8 male)
**Quality**: Medium
**Speakers**: 16 different English voices
**Character**: Variety of ages, accents, tones
**Best For**: Dialogue, variety, character narration
**Latency**: ~200ms + speaker selection
**Usage**:
```bash
# Default speaker
/agent-vibes:switch 16Speakers
# Specific speaker (0-15)
echo "I am speaker number 5" | \
piper -m ~/.claude/piper-voices/16Speakers.onnx -s 5 \
--output-file /tmp/16sp-5.wav && afplay /tmp/16sp-5.wav
```
---
## Low-Quality Voices (Faster, Lower Quality)
### When to Use Low-Quality
- Battery optimization (50% faster generation)
- Latency-sensitive applications (<150ms requirement)
- Quick prototyping or testing
- Background notifications (quality less important)
### Available Low-Quality Models
| Voice ID | Gender | Latency | Quality |
|----------|--------|---------|---------|
| en_US-danny-low | Male | ~100ms | ⭐️⭐️ |
| en_US-kathleen-low | Female | ~100ms | ⭐️⭐️ |
| fr_FR-gilles-low | Male | ~100ms | ⭐️⭐️ |
| fr_FR-siwis-low | Female | ~100ms | ⭐️⭐️ |
**Download Low-Quality Voice**:
```bash
cd ~/.claude/piper-voices
curl -L -o fr_FR-gilles-low.onnx \
"https://huggingface.co/rhasspy/piper-voices/resolve/main/fr/fr_FR/gilles/low/fr_FR-gilles-low.onnx"
curl -L -o fr_FR-gilles-low.onnx.json \
"https://huggingface.co/rhasspy/piper-voices/resolve/main/fr/fr_FR/gilles/low/fr_FR-gilles-low.onnx.json"
```
---
## High-Quality Voices (Slower, Better Quality)
### When to Use High-Quality
- Professional presentations
- Content creation (videos, podcasts)
- Demos or public showcases
- When latency is not critical
### Available High-Quality Models
| Voice ID | Gender | Latency | Quality |
|----------|--------|---------|---------|
| en_US-ryan-high | Male | ~400ms | ⭐️⭐️⭐️⭐️⭐️ |
| en_US-libritts-high | Mixed | ~400ms | ⭐️⭐️⭐️⭐️⭐️ |
| en_US-libritts_r-high | Mixed | ~400ms | ⭐️⭐️⭐️⭐️⭐️ |
| fr_FR-siwis-high | Female | ~400ms | ⭐️⭐️⭐️⭐️⭐️ |
**Download High-Quality Voice**:
```bash
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"
curl -L -o fr_FR-siwis-high.onnx.json \
"https://huggingface.co/rhasspy/piper-voices/resolve/main/fr/fr_FR/siwis/high/fr_FR-siwis-high.onnx.json"
```
---
## Additional Languages
Piper TTS supports **50+ languages**. Download additional voices from Hugging Face.
### Popular Languages Available
| Language | Voices Available | Repository |
|----------|------------------|------------|
| Spanish (es_ES) | 10+ voices | [Link](https://huggingface.co/rhasspy/piper-voices/tree/main/es/es_ES) |
| German (de_DE) | 8+ voices | [Link](https://huggingface.co/rhasspy/piper-voices/tree/main/de/de_DE) |
| Italian (it_IT) | 6+ voices | [Link](https://huggingface.co/rhasspy/piper-voices/tree/main/it/it_IT) |
| Portuguese (pt_BR) | 5+ voices | [Link](https://huggingface.co/rhasspy/piper-voices/tree/main/pt/pt_BR) |
| Russian (ru_RU) | 4+ voices | [Link](https://huggingface.co/rhasspy/piper-voices/tree/main/ru/ru_RU) |
| Chinese (zh_CN) | 3+ voices | [Link](https://huggingface.co/rhasspy/piper-voices/tree/main/zh/zh_CN) |
### Download Spanish Voice Example
```bash
cd ~/.claude/piper-voices
# Spanish male voice (Davefx - high quality)
curl -L -o es_ES-davefx-medium.onnx \
"https://huggingface.co/rhasspy/piper-voices/resolve/main/es/es_ES/davefx/medium/es_ES-davefx-medium.onnx"
curl -L -o es_ES-davefx-medium.onnx.json \
"https://huggingface.co/rhasspy/piper-voices/resolve/main/es/es_ES/davefx/medium/es_ES-davefx-medium.onnx.json"
# Test
echo "Hola, soy Claude y hablo español" | \
piper -m es_ES-davefx-medium.onnx \
--output-file /tmp/es.wav && afplay /tmp/es.wav
```
---
## Voice Selection Recommendations
### By Use Case
| Use Case | Recommended Voice | Reason |
|----------|-------------------|--------|
| **Technical Documentation** | fr_FR-tom-medium | Clear, professional, technical tone |
| **Code Reviews** | en_US-ryan-high | Authoritative, clear pronunciation |
| **Tutorials** | fr_FR-siwis-medium | Warm, friendly, educational |
| **Background Notifications** | fr_FR-gilles-low | Fast, efficient, low latency |
| **Professional Presentations** | en_US-ryan-high | Best quality, professional |
| **Variety/Dialogue** | fr_FR-mls-medium | 124 different voices |
| **Battery Optimization** | Any "-low" voice | 50% faster generation |
### By Language
| Primary Language | Best Voice | Alternative |
|------------------|------------|-------------|
| **French** | fr_FR-tom-medium | fr_FR-mls-medium (variety) |
| **English** | en_US-ryan-high | en_US-libritts-high |
| **Spanish** | es_ES-davefx-medium | es_ES-carlfm-medium |
| **German** | de_DE-thorsten-high | de_DE-kerstin-low |
---
## Voice Comparison Tool
Compare voices side-by-side:
```bash
# Create comparison script
cat > /tmp/compare-voices.sh << 'EOF'
#!/bin/bash
TEXT="$1"
VOICES=("fr_FR-tom-medium" "fr_FR-siwis-medium" "fr_FR-upmc-medium")
for voice in "${VOICES[@]}"; do
echo "Testing $voice..."
echo "$TEXT" | piper -m ~/.claude/piper-voices/${voice}.onnx \
--output-file /tmp/${voice}.wav
afplay /tmp/${voice}.wav
sleep 2
done
EOF
chmod +x /tmp/compare-voices.sh
# Compare voices
/tmp/compare-voices.sh "Bonjour, ceci est un test de comparaison"
```
---
## Resources
- **Piper Voice Repository**: https://huggingface.co/rhasspy/piper-voices
- **Audio Samples**: https://rhasspy.github.io/piper-samples/
- **Voice Training**: https://github.com/rhasspy/piper/blob/master/TRAINING.md
- **Custom Voices**: https://community.rhasspy.org/c/piper/
---
*Voice catalog maintained by [Claude Code Ultimate Guide](https://github.com/FlorianBruniaux/claude-code-ultimate-guide)*
*Last updated: 2026-01-22 | Piper TTS v1.3.0*

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*

13
machine-readable/reference.yaml
View file

@ -3,7 +3,7 @@
# Source: guide/ultimate-guide.md
# Purpose: Condensed index for LLMs to quickly answer user questions about Claude Code
version: "3.11.0"
version: "3.11.1"
updated: "2026-01-21"
# ════════════════════════════════════════════════════════════════
@ -46,6 +46,15 @@ deep_dive:
learning_capture_hook: "examples/hooks/bash/learning-capture.sh"
# Anti-patterns
vibe_coding_trap: "guide/learning-with-ai.md:81"
# TTS Integration (Agent Vibes) - Added 2026-01-22
tts_integration_guide: "examples/integrations/agent-vibes/README.md"
tts_installation: "examples/integrations/agent-vibes/installation.md"
tts_voice_catalog: "examples/integrations/agent-vibes/voice-catalog.md"
tts_troubleshooting: "examples/integrations/agent-vibes/troubleshooting.md"
tts_workflow: "guide/workflows/tts-setup.md"
tts_ai_ecosystem: "guide/ai-ecosystem.md:507"
tts_hook_example: "examples/hooks/bash/tts-selective.sh"
tts_claude_md_template: "examples/claude-md/tts-enabled.md"
# Architecture internals (guide/architecture.md)
architecture_master_loop: "guide/architecture.md:60"
architecture_tools: "guide/architecture.md:130"
@ -491,7 +500,7 @@ ecosystem:
- "Cross-links modified → Update all 4 repos"
history:
- date: "2026-01-20"
event: "Code Landing sync v3.11.0, 66 templates, cross-links"
event: "Code Landing sync v3.11.1, 66 templates, cross-links"
commit: "5b5ce62"
- date: "2026-01-20"
event: "Cowork Landing fix (paths, README, UI badges)"