agentvibes 5.4.0 → 5.5.0

package/.claude/config/audio-effects.cfg

@@ -50,3 +50,15 @@ _party_mode|compand 0.3,1 6:-70,-60,-20|agent_vibes_dark_chill_step_loop.mp3|0.4
 |||
 # Default (no agent specified) - clean with Bachata background|||
 default|reverb 20 50 50|agentvibes_soft_flamenco_loop.mp3|0.30
+|||
+# Per-LLM routing rows — looked up by play-tts.sh / play-tts.ps1 when -llm is passed|||
+# Format: llm:<name>|REVERB_PRESET|BACKGROUND_FILE|BACKGROUND_VOLUME|VOICE|PRETEXT|ENGINE|||
+|||
+# Claude Code (claude-code CLI via CLAUDECODE=1 env or AGENTVIBES_LLM=claude-code)|||
+llm:claude-code|off||||Agent Vibes Here|piper
+|||
+# GitHub Copilot Chat (VS Code MCP or AGENTVIBES_LLM=copilot)|||
+llm:copilot|off||||Agent Vibes Here|piper
+|||
+# OpenAI Codex CLI (AGENTVIBES_LLM=codex)|||
+llm:codex|off||||Agent Vibes Here|piper

package/.claude/config/background-music-enabled.txt

@@ -0,0 +1 @@
+true

package/.claude/config/background-music-position.txt

@@ -24,4 +24,4 @@ agent_vibes_arabic_v2_loop.mp3:.00000000000000000006132724
 agent_vibes_chillwave_v2_loop.mp3:14.628390
 agent_vibes_bachata_v1_loop.mp3:.00000000000000000005344000
 agent_vibes_goa_trance_v2_loop.mp3:.00000000000000000002499918
-agentvibes_soft_flamenco_loop.mp3:10.736417
+agentvibes_soft_flamenco_loop.mp3:10.584014

package/.claude/github-star-reminder.txt

@@ -1 +1 @@
-20260422
+20260427

package/.claude/hooks/bmad-speak.sh

@@ -50,11 +50,15 @@ if [[ ! -f "$PROJECT_ROOT/_bmad/_config/agent-manifest.csv" ]]; then
 fi
 
 # ---------------------------------------------------------------------------
-# Per-agent profile reader — reads from ~/.agentvibes/bmad-voice-map.json
+# Per-agent profile reader — reads from project .agentvibes/bmad-voice-map.json (falls back to global)
 # Uses node for reliable JSON parsing (jq may not be installed)
 # Returns empty string if field not found or file missing
 
-VOICE_MAP_FILE="$HOME/.agentvibes/bmad-voice-map.json"
+if [[ -f "$PROJECT_ROOT/.agentvibes/bmad-voice-map.json" ]]; then
+  VOICE_MAP_FILE="$PROJECT_ROOT/.agentvibes/bmad-voice-map.json"
+else
+  VOICE_MAP_FILE="$HOME/.agentvibes/bmad-voice-map.json"
+fi
 
 # Read a field from the per-agent profile in bmad-voice-map.json
 # Usage: read_agent_profile <agent_id> <field>

package/.claude/hooks/play-tts-piper.sh

@@ -551,8 +551,8 @@ if [[ "${AGENTVIBES_TEST_MODE:-false}" != "true" ]] && [[ "${AGENTVIBES_NO_PLAYB
     termux-media-player play "$TEMP_FILE" >/dev/null 2>&1 &
     PLAYER_PID=$!
   else
-    # Linux/WSL: Prefer paplay (PulseAudio) for best WSL audio quality
-    (paplay "$TEMP_FILE" || mpv "$TEMP_FILE" || aplay "$TEMP_FILE") >/dev/null 2>&1 &
+    # Linux/WSL: paplay with 500ms latency buffer prevents choppiness over RDP/network audio
+    (paplay --latency-msec=500 "$TEMP_FILE" || mpv "$TEMP_FILE" || aplay -B 2000000 "$TEMP_FILE") >/dev/null 2>&1 &
     PLAYER_PID=$!
   fi
 fi

package/.claude/hooks/play-tts.sh

@@ -103,8 +103,29 @@ elif [[ -f "$GLOBAL_MUTE_FILE" ]]; then
   exit 0
 fi
 
+# Parse named flags (e.g. --llm) before positional arguments.
+# This allows callers to pass: play-tts.sh --llm claude-code "text to speak"
+# Named args are extracted; remaining positional args are shifted into $1/$2/$3.
+LLM_PROVIDER="${LLM_PROVIDER:-}"
+_POSITIONAL_ARGS=()
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --llm)
+      LLM_PROVIDER="${2:-}"
+      shift 2
+      ;;
+    *)
+      _POSITIONAL_ARGS+=("$1")
+      shift
+      ;;
+  esac
+done
+set -- "${_POSITIONAL_ARGS[@]+"${_POSITIONAL_ARGS[@]}"}"
+unset _POSITIONAL_ARGS
+
 TEXT="${1:-}"
 VOICE_OVERRIDE="${2:-}"  # Optional: voice name or ID
+AGENT_PROFILE_FILE="${3:-}"  # Optional: path to agent profile file
 
 # Security: Validate inputs
 if [[ -z "$TEXT" ]]; then
@@ -397,7 +418,7 @@ fi
 # Normal single-language mode - route to appropriate provider implementation
 case "$ACTIVE_PROVIDER" in
   piper)
-    exec bash "$SCRIPT_DIR/play-tts-piper.sh" "$TEXT" "$VOICE_OVERRIDE" "$AGENT_PROFILE_FILE"
+    exec bash "$SCRIPT_DIR/play-tts-piper.sh" "$TEXT" "$VOICE_OVERRIDE" "${AGENT_PROFILE_FILE:-}"
     ;;
   soprano)
     exec bash "$SCRIPT_DIR/play-tts-soprano.sh" "$TEXT" "$VOICE_OVERRIDE"

package/.claude/hooks-windows/play-tts-windows-piper.ps1

@@ -1,164 +1,178 @@
-#
-# File: .claude/hooks-windows/play-tts-windows-piper.ps1
-#
-# AgentVibes - Windows Piper TTS Provider
-# High-quality neural TTS using Piper.exe
-#
-
-param(
-    [Parameter(Mandatory = $true)]
-    [string]$Text,
-
-    [Parameter(Mandatory = $false)]
-    [string]$VoiceOverride
-)
-
-# Configuration paths
-$ScriptPath = Split-Path -Parent $MyInvocation.MyCommand.Path
-$ProjectClaudeDir = Join-Path (Split-Path -Parent (Split-Path -Parent $ScriptPath)) ".claude"
-
-if (Test-Path $ProjectClaudeDir) {
-    $ClaudeDir = $ProjectClaudeDir
-} else {
-    $ClaudeDir = "$env:USERPROFILE\.claude"
-}
-
-# Audio cache and voice config use project-local .claude
-$AudioDir = "$ClaudeDir\audio"
-$VoiceFile = "$ClaudeDir\tts-voice-piper.txt"
-
-# Voices and Piper binary are global (shared across projects, ~100MB+)
-$UserClaudeDir = "$env:USERPROFILE\.claude"
-$VoicesDir = "$UserClaudeDir\piper-voices"
-$PiperExe = "$env:LOCALAPPDATA\Programs\Piper\piper.exe"
-
-# Ensure directories exist
-foreach ($dir in @($AudioDir, $VoicesDir)) {
-    if (-not (Test-Path $dir)) {
-        New-Item -ItemType Directory -Path $dir -Force | Out-Null
-    }
-}
-
-# Check if Piper is installed
-if (-not (Test-Path $PiperExe)) {
-    Write-Host "[ERROR] Piper not found at: $PiperExe" -ForegroundColor Red
-    Write-Host "Run: .\setup-windows.ps1 to install Piper" -ForegroundColor Yellow
-    exit 1
-}
-
-# Determine voice to use
-$VoiceName = ""
-
-if ($VoiceOverride) {
-    $VoiceName = $VoiceOverride
-}
-elseif (Test-Path $VoiceFile) {
-    $VoiceName = (Get-Content $VoiceFile -Raw).Trim()
-}
-
-# Default voice if not specified
-if (-not $VoiceName) {
-    $VoiceName = "en_US-ryan-high"
-}
-
-# Security: Validate voice name to prevent path traversal
-# Only allow alphanumeric, underscore, hyphen, and period
-if ($VoiceName -notmatch '^[a-zA-Z0-9_\-\.]+$') {
-    Write-Host "[ERROR] Invalid voice name: $VoiceName" -ForegroundColor Red
-    exit 1
-}
-
-# Resolve voice model path and validate it stays within VoicesDir
-$VoiceModelFile = [System.IO.Path]::GetFullPath("$VoicesDir\$VoiceName.onnx")
-$VoiceJsonFile = [System.IO.Path]::GetFullPath("$VoicesDir\$VoiceName.onnx.json")
-$ResolvedVoicesDir = [System.IO.Path]::GetFullPath($VoicesDir)
-if (-not $VoiceModelFile.StartsWith($ResolvedVoicesDir)) {
-    Write-Host "[ERROR] Voice path outside voices directory" -ForegroundColor Red
-    exit 1
-}
-
-# Check if voice model exists, download if missing
-if (-not (Test-Path $VoiceModelFile)) {
-    Write-Host "[DOWNLOAD] Voice model: $VoiceName" -ForegroundColor Yellow
-
-    # Try to download from Hugging Face
-    # Voice name format: {lang}_{region}-{speaker}-{quality}
-    # HF path format:    {lang}/{lang}_{region}/{speaker}/{quality}/{voicename}.onnx
-    try {
-        # Parse voice name to build correct HF path
-        # e.g. en_US-ryan-high -> en/en_US/ryan/high/en_US-ryan-high.onnx
-        if ($VoiceName -match '^([a-z]{2})_([A-Z]{2})-([a-zA-Z0-9_]+)-([a-z]+)$') {
-            $Lang = $Matches[1]
-            $LangRegion = "$($Matches[1])_$($Matches[2])"
-            $Speaker = $Matches[3]
-            $Quality = $Matches[4]
-            $HFBase = "https://huggingface.co/rhasspy/piper-voices/resolve/main/$Lang/$LangRegion/$Speaker/$Quality"
-        } else {
-            # Fallback for non-standard voice names
-            $HFBase = "https://huggingface.co/rhasspy/piper-voices/resolve/main/en/en_US/ryan/high"
-        }
-        $ModelUrl = "$HFBase/$VoiceName.onnx"
-        $JsonUrl = "$HFBase/$VoiceName.onnx.json"
-
-        Write-Host "   Downloading model..." -ForegroundColor Cyan
-        Invoke-WebRequest -Uri $ModelUrl -OutFile $VoiceModelFile -ErrorAction Stop
-        Write-Host "   Downloading config..." -ForegroundColor Cyan
-        Invoke-WebRequest -Uri $JsonUrl -OutFile $VoiceJsonFile -ErrorAction Stop
-        Write-Host "[OK] Voice model downloaded" -ForegroundColor Green
-    }
-    catch {
-        Write-Host "[ERROR] Failed to download voice model: $_" -ForegroundColor Red
-        Write-Host "Make sure you have internet connection" -ForegroundColor Yellow
-        exit 1
-    }
-}
-
-# Sanitize text for speech - strip shell metacharacters and PS special chars
-$Text = $Text -replace '\\', ' '
-$Text = $Text -replace '[{}<>|`~^$;"''()]', ''
-$Text = $Text -replace '\s+', ' '
-$Text = $Text.Trim()
-
-# Create audio file path
-$Timestamp = Get-Date -Format 'yyyyMMdd-HHmmss-ffff'
-$AudioFile = "$AudioDir\tts-$Timestamp.wav"
-
-# Synthesize with Piper
-try {
-    Write-Host "[SYNTH] Synthesizing with Piper..." -ForegroundColor Cyan
-
-    # Run Piper with text input
-    $Text | & $PiperExe `
-        --model $VoiceModelFile `
-        --output-file $AudioFile `
-        2>$null
-
-    if (-not (Test-Path $AudioFile)) {
-        Write-Host "[ERROR] Piper synthesis failed" -ForegroundColor Red
-        exit 1
-    }
-
-    # Display results
-    Write-Host "[OK] Saved to: $AudioFile" -ForegroundColor Green
-    Write-Host "[VOICE] Voice used: $VoiceName (Piper)" -ForegroundColor Green
-
-    # Play the audio using built-in Windows audio player (skip if AGENTVIBES_NO_PLAY is set)
-    if (-not $env:AGENTVIBES_NO_PLAY) {
-        $player = $null
-        try {
-            $player = New-Object System.Media.SoundPlayer $AudioFile
-            $player.PlaySync()
-        }
-        catch {
-            Write-Host "[WARNING] Could not play audio (SoundPlayer unavailable)" -ForegroundColor Yellow
-            Write-Host "Audio saved to: $AudioFile" -ForegroundColor Gray
-        }
-        finally {
-            if ($player) { $player.Dispose() }
-        }
-    }
-}
-catch {
-    Write-Host "[ERROR] Error running Piper: $_" -ForegroundColor Red
-    exit 1
-}
+#
+# File: .claude/hooks-windows/play-tts-windows-piper.ps1
+#
+# AgentVibes - Windows Piper TTS Provider
+# High-quality neural TTS using Piper.exe
+#
+
+param(
+    [Parameter(Mandatory = $true)]
+    [string]$Text,
+
+    [Parameter(Mandatory = $false)]
+    [string]$VoiceOverride
+)
+
+# Configuration paths
+$ScriptPath = Split-Path -Parent $MyInvocation.MyCommand.Path
+$ProjectClaudeDir = Join-Path (Split-Path -Parent (Split-Path -Parent $ScriptPath)) ".claude"
+
+if (Test-Path $ProjectClaudeDir) {
+    $ClaudeDir = $ProjectClaudeDir
+} else {
+    $ClaudeDir = "$env:USERPROFILE\.claude"
+}
+
+# Audio cache and voice config use project-local .claude
+$AudioDir = "$ClaudeDir\audio"
+$VoiceFile = "$ClaudeDir\tts-voice-piper.txt"
+
+# Voices and Piper binary are global (shared across projects, ~100MB+)
+$UserClaudeDir = "$env:USERPROFILE\.claude"
+$VoicesDir = "$UserClaudeDir\piper-voices"
+$PiperExe = "$env:LOCALAPPDATA\Programs\Piper\piper.exe"
+
+# Ensure directories exist
+foreach ($dir in @($AudioDir, $VoicesDir)) {
+    if (-not (Test-Path $dir)) {
+        New-Item -ItemType Directory -Path $dir -Force | Out-Null
+    }
+}
+
+# Check if Piper is installed
+if (-not (Test-Path $PiperExe)) {
+    Write-Host "[ERROR] Piper not found at: $PiperExe" -ForegroundColor Red
+    Write-Host "Run: .\setup-windows.ps1 to install Piper" -ForegroundColor Yellow
+    exit 1
+}
+
+# Determine voice to use
+$VoiceName = ""
+
+if ($VoiceOverride) {
+    $VoiceName = $VoiceOverride
+}
+elseif (Test-Path $VoiceFile) {
+    $VoiceName = (Get-Content $VoiceFile -Raw).Trim()
+}
+
+# Default voice if not specified
+if (-not $VoiceName) {
+    $VoiceName = "en_US-ryan-high"
+}
+
+# Security: Validate voice name to prevent path traversal
+# Only allow alphanumeric, underscore, hyphen, and period
+if ($VoiceName -notmatch '^[a-zA-Z0-9_\-\.]+$') {
+    Write-Host "[ERROR] Invalid voice name: $VoiceName" -ForegroundColor Red
+    exit 1
+}
+
+# Resolve voice model path and validate it stays within VoicesDir
+$VoiceModelFile = [System.IO.Path]::GetFullPath("$VoicesDir\$VoiceName.onnx")
+$VoiceJsonFile = [System.IO.Path]::GetFullPath("$VoicesDir\$VoiceName.onnx.json")
+$ResolvedVoicesDir = [System.IO.Path]::GetFullPath($VoicesDir)
+if (-not $VoiceModelFile.StartsWith($ResolvedVoicesDir)) {
+    Write-Host "[ERROR] Voice path outside voices directory" -ForegroundColor Red
+    exit 1
+}
+
+# Check if voice model exists, download if missing
+if (-not (Test-Path $VoiceModelFile)) {
+    Write-Host "[DOWNLOAD] Voice model: $VoiceName" -ForegroundColor Yellow
+
+    # Try to download from Hugging Face
+    # Voice name format: {lang}_{region}-{speaker}-{quality}
+    # HF path format:    {lang}/{lang}_{region}/{speaker}/{quality}/{voicename}.onnx
+    try {
+        # Parse voice name to build correct HF path
+        # e.g. en_US-ryan-high -> en/en_US/ryan/high/en_US-ryan-high.onnx
+        if ($VoiceName -match '^([a-z]{2})_([A-Z]{2})-([a-zA-Z0-9_]+)-([a-z]+)$') {
+            $Lang = $Matches[1]
+            $LangRegion = "$($Matches[1])_$($Matches[2])"
+            $Speaker = $Matches[3]
+            $Quality = $Matches[4]
+            $HFBase = "https://huggingface.co/rhasspy/piper-voices/resolve/main/$Lang/$LangRegion/$Speaker/$Quality"
+        } else {
+            # Fallback for non-standard voice names
+            $HFBase = "https://huggingface.co/rhasspy/piper-voices/resolve/main/en/en_US/ryan/high"
+        }
+        $ModelUrl = "$HFBase/$VoiceName.onnx"
+        $JsonUrl = "$HFBase/$VoiceName.onnx.json"
+
+        Write-Host "   Downloading model..." -ForegroundColor Cyan
+        Invoke-WebRequest -Uri $ModelUrl -OutFile $VoiceModelFile -ErrorAction Stop
+        Write-Host "   Downloading config..." -ForegroundColor Cyan
+        Invoke-WebRequest -Uri $JsonUrl -OutFile $VoiceJsonFile -ErrorAction Stop
+        Write-Host "[OK] Voice model downloaded" -ForegroundColor Green
+    }
+    catch {
+        Write-Host "[ERROR] Failed to download voice model: $_" -ForegroundColor Red
+        Write-Host "Make sure you have internet connection" -ForegroundColor Yellow
+        exit 1
+    }
+}
+
+# Sanitize text for speech - strip shell metacharacters and PS special chars
+$Text = $Text -replace '\\', ' '
+$Text = $Text -replace '[{}<>|`~^$;"''()]', ''
+$Text = $Text -replace '\s+', ' '
+$Text = $Text.Trim()
+
+# Create audio file path
+$Timestamp = Get-Date -Format 'yyyyMMdd-HHmmss-ffff'
+$AudioFile = "$AudioDir\tts-$Timestamp.wav"
+
+# Synthesize with Piper
+try {
+    Write-Host "[SYNTH] Synthesizing with Piper..." -ForegroundColor Cyan
+
+    # Run Piper with text input
+    $Text | & $PiperExe `
+        --model $VoiceModelFile `
+        --output-file $AudioFile `
+        2>$null
+
+    if (-not (Test-Path $AudioFile)) {
+        Write-Host "[ERROR] Piper synthesis failed" -ForegroundColor Red
+        exit 1
+    }
+
+    # Display results
+    Write-Host "[OK] Saved to: $AudioFile" -ForegroundColor Green
+    Write-Host "[VOICE] Voice used: $VoiceName (Piper)" -ForegroundColor Green
+
+    # Play the audio (skip if AGENTVIBES_NO_PLAY is set)
+    if (-not $env:AGENTVIBES_NO_PLAY) {
+        # Prefer ffplay: handles 22050 Hz → 48000 Hz resampling cleanly (SoundPlayer uses
+        # WinMM's low-quality resampler which produces choppy audio at non-native rates).
+        $ffplayPath = (Get-Command ffplay -ErrorAction SilentlyContinue)?.Source
+        if (-not $ffplayPath) {
+            # SSH/watcher sessions may have a minimal PATH — refresh from registry
+            $env:Path = [System.Environment]::GetEnvironmentVariable("Path","Machine") + ";" +
+                        [System.Environment]::GetEnvironmentVariable("Path","User")
+            $ffplayPath = (Get-Command ffplay -ErrorAction SilentlyContinue)?.Source
+        }
+        if ($ffplayPath) {
+            & $ffplayPath -autoexit -nodisp -loglevel quiet $AudioFile 2>$null
+        }
+        else {
+            $player = $null
+            try {
+                $player = New-Object System.Media.SoundPlayer $AudioFile
+                $player.PlaySync()
+            }
+            catch {
+                Write-Host "[WARNING] Could not play audio (SoundPlayer unavailable)" -ForegroundColor Yellow
+                Write-Host "Audio saved to: $AudioFile" -ForegroundColor Gray
+            }
+            finally {
+                if ($player) { $player.Dispose() }
+            }
+        }
+    }
+}
+catch {
+    Write-Host "[ERROR] Error running Piper: $_" -ForegroundColor Red
+    exit 1
+}

package/.claude/hooks-windows/play-tts.ps1

@@ -10,7 +10,13 @@ param(
     [string]$Text,
 
     [Parameter(Mandatory = $false, Position = 1)]
-    [string]$VoiceOverride
+    [string]$VoiceOverride,
+
+    # LLM identity for per-LLM audio routing (e.g. "claude-code", "copilot", "codex").
+    # When provided, the router looks up an `llm:<name>` row in audio-effects.cfg
+    # to apply LLM-specific voice, pretext, reverb, and engine settings.
+    [Parameter(Mandatory = $false)]
+    [string]$llm = ""
 )
 
 # Configuration paths
@@ -97,6 +103,201 @@ if ($BgEnabled -or $HasReverb) {
     } catch {}
 }
 
+# ===========================================================================
+# Per-LLM Audio Routing
+# ===========================================================================
+# When mcp-server/server.py invokes play-tts.ps1 on Windows it passes the
+# -llm flag with the active LLM identity (e.g. "claude-code", "copilot",
+# "codex").  The router reads audio-effects.cfg and looks up the row whose
+# key is `llm:<name>`, allowing each LLM to have its own voice, pretext,
+# reverb, and engine without requiring global settings to be reconfigured.
+#
+# Expected audio-effects.cfg row format (pipe-delimited):
+#   llm:<name>|REVERB_PRESET|BACKGROUND_FILE|BACKGROUND_VOLUME|VOICE|PRETEXT|ENGINE
+#
+# Column descriptions:
+#   1. Key           - Must start with "llm:" followed by the LLM name
+#   2. REVERB_PRESET - One of: off, light, medium, heavy, cathedral (or blank)
+#   3. BACKGROUND_FILE - Filename relative to .claude/audio/tracks/ (or blank)
+#   4. BACKGROUND_VOLUME - Float 0.0-1.0 (or blank for default 0.25)
+#   5. VOICE         - Provider voice name to use (or blank for global default)
+#   6. PRETEXT       - Text prepended to all TTS utterances (or blank)
+#   7. ENGINE        - Windows engine: windows-sapi, windows-piper, soprano (or blank)
+#
+# Example rows:
+#   llm:claude-code|off|||en_US-amy-medium|Agent Vibes Here|windows-piper
+#   llm:copilot|light|||en_US-ryan-low||windows-sapi
+#   llm:codex|off||||Code complete|windows-piper
+#   llm:default|off|||||
+#
+# The "default" key is always looked up when no explicit -llm flag is
+# provided.  Configure it via Setup → Default → Configure in the TUI to
+# apply consistent audio settings across all LLM sessions.
+#
+# Security: The -llm value is validated against an allowlist regex so that
+# injected values like "-rf" or path-traversal strings are rejected before
+# they can appear in lookup keys, environment variables, or file paths.
+
+# --- Validate -llm parameter format ------------------------------------------
+if ($llm -and $llm -notmatch '^[a-zA-Z0-9][a-zA-Z0-9_-]*$') {
+    Write-Host "[WARNING] play-tts.ps1: Invalid -llm value '$llm' ignored" `
+        "(must match ^[a-zA-Z0-9][a-zA-Z0-9_-]*`$)" -ForegroundColor Yellow
+    $llm = ""
+}
+
+# --- Default fallback --------------------------------------------------------
+# An empty $llm routes through the "default" pseudo-LLM.  Users who configure
+# an `llm:default` row in audio-effects.cfg get consistent audio settings for
+# every LLM that doesn't pass its own -llm flag — a convenient global override
+# that doesn't require per-LLM configuration.
+if (-not $llm) {
+    $llm = "default"
+}
+
+# --- Export LLM key for child scripts ----------------------------------------
+# Provider scripts (play-tts-windows-*.ps1) and any other downstream tooling
+# can inspect AGENTVIBES_LLM_KEY to identify which LLM is currently speaking.
+# This mirrors the `export AGENTVIBES_LLM_KEY="llm:${LLM_PROVIDER}"` line in
+# the POSIX play-tts.sh so the cross-platform contract is symmetric.
+$env:AGENTVIBES_LLM_KEY = "llm:$llm"
+
+# --- Lookup per-LLM config in audio-effects.cfg ------------------------------
+# Scan project config first, then user-profile config.  Stop at first match.
+# Variables are intentionally prefixed with _ to distinguish LLM-local state
+# from the global session state set earlier in this script.
+$_LlmVoice    = ""
+$_LlmPretext  = ""
+$_LlmReverb   = ""
+$_LlmEngine   = ""
+$_LlmBgFile   = ""
+$_LlmBgVol    = ""
+$_LlmKey      = "llm:$llm"
+
+$_AudioEffectsCfgPaths = @(
+    (Join-Path $ClaudeDir "config\audio-effects.cfg"),
+    (Join-Path $env:USERPROFILE ".claude\config\audio-effects.cfg")
+)
+
+:llmCfgSearch foreach ($_cfgFile in $_AudioEffectsCfgPaths) {
+    if ((-not $_LlmVoice) -and (-not $_LlmPretext) -and (Test-Path $_cfgFile)) {
+        $cfgContent = Get-Content $_cfgFile -ErrorAction SilentlyContinue
+        if ($null -ne $cfgContent) {
+            foreach ($_cfgLine in $cfgContent) {
+                # Skip blank lines and comment / separator lines
+                $stripped = $_cfgLine.Trim()
+                if ($stripped.Length -eq 0 -or $stripped.StartsWith('#')) { continue }
+
+                # Split on pipe; expect at least the key column
+                $_cols = $_cfgLine -split '\|'
+                if ($_cols.Count -ge 1 -and $_cols[0].Trim() -eq $_LlmKey) {
+                    # Unpack columns defensively — missing columns stay empty
+                    if ($_cols.Count -ge 2) { $_LlmReverb  = $_cols[1].Trim() }
+                    if ($_cols.Count -ge 3) { $_LlmBgFile  = $_cols[2].Trim() }
+                    if ($_cols.Count -ge 4) { $_LlmBgVol   = $_cols[3].Trim() }
+                    if ($_cols.Count -ge 5) { $_LlmVoice   = $_cols[4].Trim() }
+                    if ($_cols.Count -ge 6) { $_LlmPretext = $_cols[5].Trim() }
+                    if ($_cols.Count -ge 7) { $_LlmEngine  = $_cols[6].Trim() }
+                    break llmCfgSearch
+                }
+            }
+        }
+    }
+}
+
+# --- Voice priority order (highest wins) -------------------------------------
+# 1. Explicit -VoiceOverride parameter (caller always wins)
+# 2. LLM-specific voice from audio-effects.cfg llm:<key> row
+# 3. BMAD agent voice from bmad-voice-map.json (resolved in provider scripts)
+# 4. Global active voice from tts-provider.txt / active-voice.txt
+
+# Apply LLM-specific voice only when no explicit -VoiceOverride was passed
+if ($_LlmVoice -and -not $VoiceOverride) {
+    $VoiceOverride = $_LlmVoice
+}
+
+# --- Apply LLM-specific pretext ----------------------------------------------
+# Prepend the configured pretext (e.g. "Agent Vibes Here") to the speech
+# text.  Guard against double-prefixing on re-entrant or looped calls by
+# checking whether the text already starts with the pretext string.
+if ($_LlmPretext -and -not $Text.StartsWith($_LlmPretext)) {
+    $Text = "$_LlmPretext, $Text"
+}
+
+# --- Reverb override from per-LLM config -------------------------------------
+# If the llm:<key> row specifies a reverb preset, override the file-based
+# $ReverbLevel that was set from reverb-level.txt earlier.  The allowlist
+# check is repeated here so a malformed config row can't inject arbitrary
+# strings into the ffmpeg filter chain.
+if ($_LlmReverb) {
+    $validReverbLevels = @("off", "light", "medium", "heavy", "cathedral")
+    if ($validReverbLevels -contains $_LlmReverb) {
+        $ReverbLevel = $_LlmReverb
+        $HasReverb = $ReverbLevel -ne "off"
+        # If the LLM config enables reverb and ffmpeg wasn't found yet, retry
+        if ($HasReverb -and -not $HasFfmpeg) {
+            try { $null = Get-Command ffmpeg -ErrorAction Stop; $HasFfmpeg = $true } catch {}
+        }
+    }
+}
+
+# --- Apply LLM-specific engine override --------------------------------------
+# Allowed local Windows engines: windows-sapi, windows-piper, soprano.
+# Transport providers (ssh-remote etc.) are not listed because they forward
+# TTS to a remote host — overriding with a local engine would synthesize on
+# the wrong machine.
+if ($_LlmEngine) {
+    $allowedLocalEngines = @("windows-sapi", "windows-piper", "soprano")
+    if ($allowedLocalEngines -contains $_LlmEngine) {
+        switch ($_LlmEngine) {
+            "windows-sapi"  { $ProviderScript = "$HooksDir\play-tts-windows-sapi.ps1"  }
+            "windows-piper" { $ProviderScript = "$HooksDir\play-tts-windows-piper.ps1" }
+            "soprano"       { $ProviderScript = "$HooksDir\play-tts-soprano.ps1"        }
+        }
+    } else {
+        Write-Host "[INFO] play-tts.ps1: Unrecognised engine '$_LlmEngine' in audio-effects.cfg — keeping default provider" -ForegroundColor DarkGray
+    }
+}
+
+# --- BMAD Party Mode note ----------------------------------------------------
+# When BMAD party mode is active, multiple agents speak in rapid succession.
+# Each agent's voice is resolved from bmad-voice-map.json inside the provider
+# scripts — that BMAD-level routing is independent of this per-LLM system.
+# The -llm flag is still used to set AGENTVIBES_LLM_KEY and can supply a
+# background music track and reverb preset that stays consistent throughout
+# the entire party mode session regardless of which agent is speaking.
+
+# --- Diagnostic output -------------------------------------------------------
+# Set AGENTVIBES_VERBOSE=1 in the shell environment to print routing state.
+if ($env:AGENTVIBES_VERBOSE -eq "1") {
+    Write-Host "[DEBUG] play-tts.ps1 LLM routing: llm=$llm | voice=$VoiceOverride | engine=$_LlmEngine | pretext=$_LlmPretext" -ForegroundColor DarkCyan
+    Write-Host "[DEBUG] play-tts.ps1 LLM routing: reverb=$ReverbLevel | HasFfmpeg=$HasFfmpeg | BgEnabled=$BgEnabled | script=$ProviderScript" -ForegroundColor DarkCyan
+}
+
+# ===========================================================================
+# End of Per-LLM Audio Routing
+# ===========================================================================
+
+# Helper: play a WAV file preferring ffplay over SoundPlayer.
+# SoundPlayer uses WinMM's low-quality resampler (22050 Hz → 48000 Hz is choppy);
+# ffplay uses libswresample with sinc resampling — no artefacts.
+function Invoke-AudioPlay {
+    param([string]$FilePath)
+    $fp = (Get-Command ffplay -ErrorAction SilentlyContinue)?.Source
+    if (-not $fp) {
+        # Watcher sessions may inherit a minimal PATH — refresh from registry
+        $env:Path = [System.Environment]::GetEnvironmentVariable("Path","Machine") + ";" +
+                    [System.Environment]::GetEnvironmentVariable("Path","User")
+        $fp = (Get-Command ffplay -ErrorAction SilentlyContinue)?.Source
+    }
+    if ($fp) {
+        & $fp -autoexit -nodisp -loglevel quiet $FilePath 2>$null
+    } else {
+        $p = $null
+        try   { $p = New-Object System.Media.SoundPlayer $FilePath; $p.PlaySync() }
+        finally { if ($p) { $p.Dispose() } }
+    }
+}
+
 # If background music or reverb enabled and ffmpeg available, tell provider to skip playback
 if (($BgEnabled -or $HasReverb) -and $HasFfmpeg) {
     $env:AGENTVIBES_NO_PLAY = "1"
@@ -204,61 +405,27 @@ if (($BgEnabled -or $HasReverb) -and $HasFfmpeg) {
 
                     if ($proc.ExitCode -eq 0 -and (Test-Path $MixedFile) -and (Get-Item $MixedFile).Length -gt 0) {
                         # Play the mixed audio
-                        $player = $null
                         try {
-                            $player = New-Object System.Media.SoundPlayer $MixedFile
-                            $player.PlaySync()
+                            Invoke-AudioPlay $MixedFile
                         } catch {
                             Write-Host "[WARNING] Mixed playback failed, playing voice only" -ForegroundColor Yellow
-                            $player2 = $null
-                            try {
-                                $player2 = New-Object System.Media.SoundPlayer $voicePath
-                                $player2.PlaySync()
-                            } finally {
-                                if ($player2) { $player2.Dispose() }
-                            }
-                        } finally {
-                            if ($player) { $player.Dispose() }
+                            Invoke-AudioPlay $voicePath
                         }
                     } else {
                         # Mixing failed, play voice only
-                        $player = $null
-                        try {
-                            $player = New-Object System.Media.SoundPlayer $voicePath
-                            $player.PlaySync()
-                        } finally {
-                            if ($player) { $player.Dispose() }
-                        }
+                        Invoke-AudioPlay $voicePath
                     }
                 } catch {
                     # ffmpeg failed, play voice only
-                    $player = $null
-                    try {
-                        $player = New-Object System.Media.SoundPlayer $voicePath
-                        $player.PlaySync()
-                    } finally {
-                        if ($player) { $player.Dispose() }
-                    }
+                    Invoke-AudioPlay $voicePath
                 }
             } else {
                 # No background track found, play voice only
-                $player = $null
-                try {
-                    $player = New-Object System.Media.SoundPlayer $voicePath
-                    $player.PlaySync()
-                } finally {
-                    if ($player) { $player.Dispose() }
-                }
+                Invoke-AudioPlay $voicePath
             }
         } else {
             # No background music, play the (possibly reverbed) voice
-            $player = $null
-            try {
-                $player = New-Object System.Media.SoundPlayer $voicePath
-                $player.PlaySync()
-            } finally {
-                if ($player) { $player.Dispose() }
-            }
+            Invoke-AudioPlay $voicePath
         }
     }
 } else {

package/README.md

@@ -11,7 +11,7 @@
 [![Publish](https://github.com/paulpreibisch/AgentVibes/actions/workflows/publish.yml/badge.svg)](https://github.com/paulpreibisch/AgentVibes/actions/workflows/publish.yml)
 [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-**Author**: Paul Preibisch ([@997Fire](https://x.com/997Fire)) | **Version**: v5.4.0
+**Author**: Paul Preibisch ([@997Fire](https://x.com/997Fire)) | **Version**: v5.5
 
 ---
 
@@ -40,11 +40,21 @@ Whether you're coding in Claude Code, chatting in Claude Desktop, using Warp Ter
 
 ---
 
-## 🌟 NEW FEATURE HIGHLIGHTS
+## 🌟 NEW IN v5.5 — Per-LLM Audio Routing
 
-### 🎤 Agent Vibes v1.0 Voice Browser
+Give **each LLM its own voice, pretext, and music** — Claude Code, Copilot, and Codex can all sound different without touching global settings.
+
+- Add `llm:<name>|...|voice|pretext|engine` rows to `audio-effects.cfg`
+- MCP server auto-detects which LLM is calling and passes `--llm <key>`
+- Configure via **Setup → Default → Configure** in the TUI
+
+Also fixed: Windows installer crash (`spinner.info is not a function`) on **reinstall** with an older global AgentVibes install.
+
+---
 
-![Voice Browser Banner](docs/installation-screenshots/voice-browser-screenshot.png)
+## v5.4 — TUI Installer, Spinner Fix & Dependency Cleanup
+
+### 🎤 Agent Vibes v1.0 Voice Browser
 
 **🎤 Browse, Sample & Install 914 Voices in Real-Time**
 
@@ -297,8 +307,6 @@ All 50+ Piper voices AgentVibes provides are sourced from Hugging Face's open-so
 
 **Browse and sample 914 voices in real-time!**
 
-![AgentVibes Voice Browser](docs/installation-screenshots/voice-browser-screenshot.png)
-
 ```bash
 npx agentvibes-voice-browser
 ```
@@ -453,9 +461,6 @@ macOS ships with bash 3.2 (from 2007). After this, everything works perfectly!
 
 **The easiest way to find your perfect voice!**
 
-![AgentVibes Voice Browser](docs/installation-screenshots/voice-browser-screenshot.png)
-*Browse, sample, and install from 914 voices with real-time audio preview*
-
 ### Launch the Browser
 
 ```bash

package/RELEASE_NOTES.md

@@ -1,5 +1,45 @@
 # AgentVibes Release Notes
 
+## 🎵 v5.5.0 — Per-LLM Audio Routing & Windows Installer Resilience
+
+**Released:** 2026-04-27
+
+### 🆕 Per-LLM Audio Routing
+Each LLM (Claude Code, Copilot, Codex) can now have its own voice, pretext, reverb, and
+background-music settings. The MCP server passes `--llm <key>` to both `play-tts.sh`
+(Linux/macOS) and `play-tts.ps1` (Windows), and the scripts look up `llm:<key>` rows in
+`audio-effects.cfg`. Default rows for `claude-code`, `copilot`, and `codex` ship out of the
+box; configure them via **Setup → Default → Configure** in the TUI.
+
+### 🐛 Windows Installer Crash Fix
+Fixed `spinner.info is not a function` error that crashed AgentVibes **reinstalls** on Windows
+when users had an older global install. All 10 file-copy functions in the installer now wrap
+their spinner with `createRobustSpinner()` so stale callers can never cause a crash regardless
+of which methods they expose.
+
+### 🎶 Windows Background Music Parity
+Windows TTS playback now prefers `ffplay` (sinc resampling, no artefacts) over the low-quality
+WinMM `SoundPlayer` resampler. The new `Invoke-AudioPlay` helper handles the fallback
+transparently — if `ffplay` is unavailable, `SoundPlayer` is used as before.
+
+### 🎉 Party Mode Cross-Platform Entry Point
+BMAD party mode step files and the Copilot skill now consistently reference
+`node bin/bmad-speak.js` — the single cross-platform entry point that delegates to
+`bmad-speak.ps1` on Windows and `bmad-speak.sh` elsewhere.
+
+### 🔧 Other Fixes
+- `play-tts.sh` now accepts a named `--llm <key>` flag in addition to the `LLM_PROVIDER` env var
+- `mcp-server/server.py` routes `AGENTVIBES_LLM` → `CLAUDECODE=1` → `AGENTVIBES_MCP_FALLBACK`
+  priority chain and forwards the resolved key as `-llm`/`--llm` to TTS scripts
+- Added `audio-effects.cfg` rows for `llm:claude-code`, `llm:copilot`, `llm:codex`
+- Added `command-routing.test.js` and `ConfigService` unit tests
+- npm pack content guard now catches untracked publishable files
+
+### 📊 Technical
+- 231 tests passing (0 failures)
+
+---
+
 ## 🎛️ v5.4.0 — TUI Installer, Spinner Fix & Dependency Cleanup
 
 **Released:** 2026-04-22

package/bin/agentvibes.js

@@ -75,6 +75,16 @@ export function resolveStartTab(args, configService) {
     return { startTab: 'install' };
   }
 
+  if (cmd === 'update') {
+    // Always route update to CLI installer (src/installer.js)
+    return { cliUpdate: true, args: args.slice(1) };
+  }
+
+  if (cmd === 'uninstall') {
+    // Always route uninstall to CLI installer (src/installer.js)
+    return { cliUninstall: true, args: args.slice(1) };
+  }
+
   if (cmd === 'config' || cmd === 'configure') {
     return { startTab: 'settings' };
   }
@@ -154,6 +164,24 @@ if (_argv1 === _thisFile) {
     process.exit(0);
   }
 
+  if (result.cliUpdate) {
+    const installerPath = path.resolve(__dirname, '..', 'src', 'installer.js');
+    execFileSync(process.execPath, [installerPath, 'update', ...result.args], {
+      stdio: 'inherit',
+      shell: false,
+    });
+    process.exit(0);
+  }
+
+  if (result.cliUninstall) {
+    const installerPath = path.resolve(__dirname, '..', 'src', 'installer.js');
+    execFileSync(process.execPath, [installerPath, 'uninstall', ...result.args], {
+      stdio: 'inherit',
+      shell: false,
+    });
+    process.exit(0);
+  }
+
   launchConsole({ startTab: result.startTab }).catch(err => {
     process.stderr.write(`Failed to launch AgentVibes console: ${err.message}\n`);
     process.exit(1);

package/mcp-server/server.py

@@ -192,6 +192,17 @@ class AgentVibesServer:
                 original_language = await self._get_language()
                 await self._run_script(self.LANGUAGE_MANAGER_SCRIPT, ["set", language])
 
+            # Resolve LLM key: AGENTVIBES_LLM > CLAUDECODE=1 > AGENTVIBES_MCP_FALLBACK > "default"
+            llm_key = os.environ.get("AGENTVIBES_LLM", "").strip()
+            if llm_key and not _re.match(r"^[a-zA-Z0-9][a-zA-Z0-9_-]*$", llm_key):
+                llm_key = ""
+            if not llm_key and os.environ.get("CLAUDECODE", "").strip() == "1":
+                llm_key = "claude-code"
+            if not llm_key:
+                fallback = os.environ.get("AGENTVIBES_MCP_FALLBACK", "").strip()
+                if fallback and _re.match(r"^[a-zA-Z0-9][a-zA-Z0-9_-]*$", fallback):
+                    llm_key = fallback
+
             # Call the TTS script via appropriate shell
             tts_script = "play-tts.ps1" if self.is_windows else "play-tts.sh"
             play_tts = self.hooks_dir / tts_script
@@ -199,8 +210,13 @@ class AgentVibesServer:
                 args = ["powershell", "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", str(play_tts), text]
                 if voice:
                     args.extend(["-VoiceOverride", voice])
+                if llm_key:
+                    args.extend(["-llm", llm_key])
             else:
-                args = ["bash", str(play_tts), text]
+                args = ["bash", str(play_tts)]
+                if llm_key:
+                    args.extend(["--llm", llm_key])
+                args.append(text)
                 if voice:
                     args.append(voice)
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "agentvibes",
-  "version": "5.4.0",
+  "version": "5.5.0",
   "description": "Now your AI Agents can finally talk back! Professional TTS voice for Claude Code, Claude Desktop (via MCP), and Clawdbot with multi-provider support.",
   "homepage": "https://agentvibes.org",
   "keywords": [

package/src/console/tabs/music-tab.js

@@ -185,12 +185,15 @@ export function scanTracks() {
   const tracksDir = _getTracksDir();
   try {
     const files = fs.readdirSync(tracksDir);
+    const mp3s = files.filter(f => /\.mp3$/i.test(f));
+    // If the directory exists but has no mp3s (e.g. empty npm package dir),
+    // fall back to the static catalog so bundled tracks always show.
+    if (mp3s.length === 0) return BUILT_IN_TRACK_CATALOG.map(t => ({ ...t, isBuiltIn: true }));
     const builtInIds = new Set(BUILT_IN_TRACK_CATALOG.map(t => t.id));
     // Sort by the alphabetic part of the label (skip leading emoji/symbols)
     // so the order reflects the track NAME, not the emoji codepoint.
     const _sortKey = (s) => s.replace(/^[^a-zA-Z]+/, '');
-    return files
-      .filter(f => /\.mp3$/i.test(f))
+    return mp3s
       .map(f => ({ id: f, label: formatTrackLabel(f), isBuiltIn: builtInIds.has(f) }))
       .sort((a, b) => _sortKey(a.label).localeCompare(_sortKey(b.label), undefined, { sensitivity: 'base' }));
   } catch {

package/src/console/tabs/voices-tab.js

@@ -133,6 +133,10 @@ function loadCatalog() {
   // Build lookup map for O(1) access by voiceId
   _catalogMap = new Map();
   for (const c of _catalogEntries) _catalogMap.set(c.voiceId, c);
+
+  // Patch libritts_r onnx.json files so their speaker IDs become friendly names.
+  // Must run after catalog loads so the name mapping is available.
+  patchLibriTTSSpeakerNames();
 }
 
 /**
@@ -142,45 +146,48 @@ function loadCatalog() {
  * Safe to call multiple times — skips if already patched.
  */
 function patchLibriTTSSpeakerNames() {
+  // Load catalog once for all models
+  const catalogPath = path.resolve(__dirname, '..', '..', '..', 'voice-assignments.json');
+  if (!fs.existsSync(catalogPath)) return;
+  let speakers;
   try {
-    const jsonPath = path.join(PIPER_VOICES_DIR, 'en_US-libritts-high.onnx.json');
-    if (!fs.existsSync(jsonPath)) return;
-    const data = JSON.parse(fs.readFileSync(jsonPath, 'utf8'));
-    if (!data.speaker_id_map || data.num_speakers <= 1) return;
-
-    const names = Object.keys(data.speaker_id_map);
-    // Already patched if first name doesn't start with 'p' followed by digits
-    if (names.length > 0 && !/^p\d+$/.test(names[0])) return;
-
-    // Build index → p-name reverse map
-    const indexToP = {};
-    for (const [pname, idx] of Object.entries(data.speaker_id_map)) {
-      indexToP[idx] = pname;
-    }
+    speakers = JSON.parse(fs.readFileSync(catalogPath, 'utf8')).libritts_speakers ?? {};
+  } catch { return; }
+
+  // Models to patch and how to detect unpatched keys:
+  //   libritts-high  → raw keys are p-prefixed corpus IDs (p3922, p8699, …)
+  //   libritts_r-*   → raw keys are plain numeric corpus IDs (3922, 8699, …)
+  const MODELS = [
+    { file: 'en_US-libritts-high.onnx.json',   notPatched: (k) => /^p\d+$/.test(k) },
+    { file: 'en_US-libritts_r-medium.onnx.json', notPatched: (k) => /^\d+$/.test(k) },
+    { file: 'en_US-libritts_r-high.onnx.json',   notPatched: (k) => /^\d+$/.test(k) },
+  ];
+
+  for (const { file, notPatched } of MODELS) {
+    try {
+      const jsonPath = path.join(PIPER_VOICES_DIR, file);
+      if (!fs.existsSync(jsonPath)) continue;
+      const data = JSON.parse(fs.readFileSync(jsonPath, 'utf8'));
+      if (!data.speaker_id_map || data.num_speakers <= 1) continue;
 
-    // Load friendly names from catalog
-    const catalogPath = path.resolve(__dirname, '..', '..', '..', 'voice-assignments.json');
-    if (!fs.existsSync(catalogPath)) return;
-    const catalog = JSON.parse(fs.readFileSync(catalogPath, 'utf8'));
-    const speakers = catalog.libritts_speakers ?? {};
-
-    // Rebuild speaker_id_map with friendly names
-    const newMap = {};
-    for (const [idx, pname] of Object.entries(indexToP)) {
-      const friendly = speakers[idx]?.voice_name;
-      if (friendly) {
-        newMap[friendly] = parseInt(idx, 10);
-      } else {
-        newMap[pname] = parseInt(idx, 10);
+      const names = Object.keys(data.speaker_id_map);
+      // Skip if already patched (first key is a friendly name, not a raw corpus ID)
+      if (names.length === 0 || !notPatched(names[0])) continue;
+
+      // Values are 0-based sequential indices into the model — use as catalog key
+      const newMap = {};
+      for (const [rawKey, idx] of Object.entries(data.speaker_id_map)) {
+        const friendly = speakers[String(idx)]?.voice_name;
+        newMap[friendly ?? rawKey] = idx;
       }
-    }
 
-    data.speaker_id_map = newMap;
-    // Verify file ownership before writing (security: CLAUDE.md)
-    const stat = fs.statSync(jsonPath);
-    if (typeof process.getuid === 'function' && stat.uid !== process.getuid()) return;
-    fs.writeFileSync(jsonPath, JSON.stringify(data, null, 2), 'utf8');
-  } catch { /* non-fatal */ }
+      data.speaker_id_map = newMap;
+      // Verify file ownership before writing (security: CLAUDE.md)
+      const stat = fs.statSync(jsonPath);
+      if (typeof process.getuid === 'function' && stat.uid !== process.getuid()) continue;
+      fs.writeFileSync(jsonPath, JSON.stringify(data, null, 2), 'utf8');
+    } catch { /* non-fatal — skip this model */ }
+  }
 }
 
 // Column widths for the multi-column voice list
@@ -417,9 +424,9 @@ export function parseMultiSpeaker(voiceId) {
     try {
       const data = JSON.parse(fs.readFileSync(jsonPath, 'utf8'));
       let speakerId = data.speaker_id_map?.[speakerName] ?? null;
-      // Fallback: if the .onnx.json still has raw p-names (not yet patched),
+      // Fallback: if the .onnx.json still has raw corpus IDs (not yet patched),
       // look up the numeric speaker ID from voice-assignments.json catalog.
-      if (speakerId == null && model === 'en_US-libritts-high') {
+      if (speakerId == null && (model === 'en_US-libritts-high' || /^en_US-libritts_r-/.test(model))) {
         try {
           const catalogPath = path.resolve(__dirname, '..', '..', '..', 'voice-assignments.json');
           const catalog = JSON.parse(fs.readFileSync(catalogPath, 'utf8'));
@@ -443,6 +450,9 @@ export function parseMultiSpeaker(voiceId) {
  * @returns {string[]}
  */
 export function scanInstalledVoices() {
+  // Ensure catalog is loaded and libritts_r onnx.json files are patched
+  // before we read their speaker_id_map keys (otherwise we get raw corpus IDs).
+  loadCatalog();
   try {
     const files = fs.readdirSync(PIPER_VOICES_DIR);
     const onnxFiles = files
@@ -588,6 +598,30 @@ export function getVoiceMeta(voiceId) {
       _metaCache.set(voiceId, result);
       return result;
     }
+    // libritts_r variants share speaker names with libritts-high after patching
+    if (/^en_US-libritts_r-/.test(ms.model)) {
+      // After patching: speakerName is a friendly name — look up in libritts-high catalog
+      const highCat = _catalogMap.get(`en_US-libritts-high${MS_SEP}${ms.speakerName}`);
+      if (highCat) {
+        const result = { displayName: highCat.displayName, gender: highCat.gender, provider: `Piper (${ms.model})` };
+        _metaCache.set(voiceId, result);
+        return result;
+      }
+      // Before patching: speakerName is a raw numeric corpus ID — resolve via onnx.json value
+      if (/^\d+$/.test(ms.speakerName)) {
+        try {
+          const jsonPath = path.join(PIPER_VOICES_DIR, ms.model + '.onnx.json');
+          const data = JSON.parse(fs.readFileSync(jsonPath, 'utf8'));
+          const seqIdx = data.speaker_id_map?.[ms.speakerName];
+          if (seqIdx != null && _catalogEntries[seqIdx]) {
+            const cat = _catalogEntries[seqIdx];
+            const result = { displayName: cat.displayName, gender: cat.gender, provider: `Piper (${ms.model})` };
+            _metaCache.set(voiceId, result);
+            return result;
+          }
+        } catch { /* fall through */ }
+      }
+    }
     // Fallback for speakers not in the catalog (e.g. 16Speakers model)
     const displayName = uniquifyVoiceName(ms.speakerName.replace(/_/g, ' '));
     const result = {

package/src/installer.js

@@ -3249,6 +3249,7 @@ async function handleTermuxSshConfiguration() {
  * @returns {Promise<{count: number, boxen: string}>} Number of files copied and boxen content
  */
 async function copyCommandFiles(targetDir, spinner) {
+  spinner = createRobustSpinner(spinner);
   spinner.start('Installing /agent-vibes slash commands...');
   const srcCommandsDir = path.join(__dirname, '..', '.claude', 'commands', 'agent-vibes');
   const commandsDir = path.join(targetDir, '.claude', 'commands');
@@ -3462,6 +3463,7 @@ function buildHookInstallationBoxen(installedFiles, failedFiles) {
  * @returns {Promise<{count: number, boxen: string|null}>} Number of files copied and boxen content
  */
 async function copyHookFiles(targetDir, spinner) {
+  spinner = createRobustSpinner(spinner);
   spinner.start('Installing TTS helper scripts...');
   const hooksSubdir = isNativeWindows() ? 'hooks-windows' : 'hooks';
   const srcHooksDir = path.join(__dirname, '..', '.claude', hooksSubdir);
@@ -3516,6 +3518,7 @@ async function copyHookFiles(targetDir, spinner) {
  * @returns {Promise<{count: number, boxen: string|null}>} Number of files copied and boxen content
  */
 async function copyPersonalityFiles(targetDir, spinner) {
+  spinner = createRobustSpinner(spinner);
   spinner.start('Installing personality templates...');
   const srcPersonalitiesDir = path.join(__dirname, '..', '.claude', 'personalities');
   const destPersonalitiesDir = path.join(targetDir, '.claude', 'personalities');
@@ -3598,6 +3601,7 @@ async function copyPersonalityFiles(targetDir, spinner) {
  * @returns {Promise<number>} Number of files copied
  */
 async function copyPluginFiles(targetDir, spinner) {
+  spinner = createRobustSpinner(spinner);
   spinner.start('Installing BMAD plugin files...');
   const srcPluginsDir = path.join(__dirname, '..', '.claude', 'plugins');
   const destPluginsDir = path.join(targetDir, '.claude', 'plugins');
@@ -3632,6 +3636,7 @@ async function copyPluginFiles(targetDir, spinner) {
  * @returns {Promise<number>} Number of files copied
  */
 async function copyBmadConfigFiles(targetDir, spinner) {
+  spinner = createRobustSpinner(spinner);
   spinner.start('Installing BMAD config files...');
   const srcBmadDir = path.join(__dirname, '..', '.agentvibes', 'bmad');
   const destBmadDir = path.join(targetDir, '.agentvibes', 'bmad');
@@ -3664,6 +3669,7 @@ async function copyBmadConfigFiles(targetDir, spinner) {
  * @returns {Promise<{count: number, boxen: string}>} Number of files copied and boxen content
  */
 async function copyBackgroundMusicFiles(targetDir, spinner) {
+  spinner = createRobustSpinner(spinner);
   spinner.start('Installing background music tracks...');
   const srcBackgroundsDir = path.join(__dirname, '..', '.claude', 'audio', 'tracks');
   const destBackgroundsDir = path.join(targetDir, '.claude', 'audio', 'tracks');
@@ -3786,6 +3792,7 @@ async function copyBackgroundMusicFiles(targetDir, spinner) {
  * @returns {Promise<number>} Number of files copied
  */
 async function copyConfigFiles(targetDir, spinner) {
+  spinner = createRobustSpinner(spinner);
   spinner.start('Installing configuration files...');
   const srcConfigDir = path.join(__dirname, '..', '.claude', 'config');
   const destConfigDir = path.join(targetDir, '.claude', 'config');
@@ -3848,6 +3855,7 @@ async function copyConfigFiles(targetDir, spinner) {
  * @param {Object} spinner - Ora spinner instance
  */
 async function copyCodexFiles(targetDir, spinner) {
+  spinner = createRobustSpinner(spinner);
   spinner.start('Installing Codex integration files...');
   const srcCodexDir = path.join(__dirname, '..', '.codex');
   const destCodexDir = path.join(targetDir, '.codex');
@@ -3901,6 +3909,7 @@ async function copyCodexFiles(targetDir, spinner) {
  * @param {Object} spinner - Ora spinner instance
  */
 async function configureSessionStartHook(targetDir, spinner) {
+  spinner = createRobustSpinner(spinner);
   spinner.start('Configuring AgentVibes hook for automatic TTS...');
   const claudeDir = path.join(targetDir, '.claude');
   const settingsPath = path.join(claudeDir, 'settings.json');
@@ -3956,6 +3965,7 @@ async function configureSessionStartHook(targetDir, spinner) {
  * @param {Object} spinner - Ora spinner instance
  */
 async function configurePartyModeHook(targetDir, spinner, homeDirOverride) {
+  spinner = createRobustSpinner(spinner);
   spinner.start('Configuring BMAD party mode TTS hook...');
   const homeDir = homeDirOverride || os.homedir();
   const globalClaudeDir = path.join(homeDir, '.claude');

package/src/services/llm-provider-service.js

@@ -198,7 +198,7 @@ export async function installClaudeMcp(targetDir) {
 
   try {
     // Copy hooks, commands, config, personality, plugin, bmad config files
-    const silentSpinner = { start: () => {}, succeed: () => {}, fail: () => {} };
+    const silentSpinner = { start: () => {}, stop: () => {}, succeed: () => {}, fail: () => {}, warn: () => {}, info: () => {}, stopAndPersist: () => {}, get text() { return ''; }, set text(_) {}, get isSpinning() { return false; } };
     const installer = await import('../installer.js');
     await installer.copyHookFiles(targetDir, silentSpinner);
     await installer.copyCommandFiles(targetDir, silentSpinner);