claude-code-ultimate-guide/examples/integrations/agent-vibes/troubleshooting.md

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

# 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:

# Unmute
rm .claude/agentvibes-muted
rm ~/.agentvibes-muted 2>/dev/null

# Or in Claude Code
/agent-vibes:unmute

If provider misconfigured:

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

# Verify
cat .claude/tts-provider.txt

If voice missing:

# 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:

# 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

# 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

# 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:

# 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:

# 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

# 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):

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:

# 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:

# 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):

/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

# 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

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

# Check if flock is available
which flock || /opt/homebrew/opt/util-linux/bin/flock --version

Solution

# 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)

# 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

# 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

# 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:

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
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 Last updated: 2026-01-22 | Agent Vibes v3.0.0