agentvibes 5.10.1 → 5.11.1

package/.claude/hooks/piper-download-voices.sh

@@ -48,25 +48,48 @@ source "$SCRIPT_DIR/piper-voice-manager.sh"
 
 # Parse command line arguments
 AUTO_YES=false
-if [[ "$1" == "--yes" ]] || [[ "$1" == "-y" ]]; then
-  AUTO_YES=true
-fi
+INCLUDE_LIBRITTS=false
+for arg in "$@"; do
+  case "$arg" in
+    --yes|-y) AUTO_YES=true ;;
+    --libritts) INCLUDE_LIBRITTS=true ;;
+  esac
+done
 
 # Common voice models to download
+# Includes all models required by voice-assignments.json (voices-tab curated voices)
+# plus BMAD agent voices.
 COMMON_VOICES=(
-  "en_US-ryan-high"          # Default, expressive male (30MB) - BMAD: John (pm)
-  "en_US-amy-medium"         # Warm female (13MB) - BMAD: Mary (analyst)
-  "en_US-hfc_female-medium"  # Professional female (13MB) - BMAD: Amelia (dev)
-  "en_US-lessac-medium"      # Clear female (13MB) - BMAD: Murat (tea) - NOTE: Female voice
-  "en_US-danny-low"          # Calm male (13MB) - BMAD: Winston (architect)
-  "en_US-bryce-medium"       # Professional male (13MB) - BMAD: Bob (sm)
-  "en_US-kathleen-low"       # Clear female (13MB) - BMAD: Paige (tech-writer)
-  "en_US-kusal-medium"       # Male voice (13MB) - BMAD: Saif (frame-expert)
-  "en_US-kristin-medium"     # Female voice (13MB) - BMAD: Sally (ux-designer)
-  "en_US-libritts_r-medium"  # Premium male (57MB) - BMAD: BMad Master (NOTE: Changed from -high to -medium, -high doesn't exist)
-  "en_US-libritts-high"      # Premium quality (57MB)
+  # --- Voices-tab curated voices (voice-assignments.json: curated_voices) ---
+  "en_US-ryan-high"                    # Ryan — expressive male (30MB)
+  "en_US-joe-medium"                   # Joe — natural male (13MB)
+  "en_GB-alan-medium"                  # Alan — British male (13MB)
+  "en_US-kusal-medium"                 # Marcus — male (13MB)
+  "en_US-john-medium"                  # John — male (13MB)
+  "en_US-lessac-high"                  # Katherine — clear female high-quality (30MB)
+  "en_US-ljspeech-high"               # Linda — female high-quality (30MB)
+  "en_US-amy-medium"                   # Amy — warm female (13MB)
+  "en_US-kristin-medium"              # Kristin — female (13MB)
+  "en_GB-southern_english_female-low" # Charlotte — British female (13MB)
+  # --- Additional BMAD agent voices ---
+  "en_US-hfc_female-medium"           # Professional female (13MB) - BMAD: Amelia (dev)
+  "en_US-lessac-medium"               # Clear female (13MB) - BMAD: Murat (tea)
+  "en_US-danny-low"                   # Calm male (13MB) - BMAD: Winston (architect)
+  "en_US-bryce-medium"                # Professional male (13MB) - BMAD: Bob (sm)
+  "en_US-kathleen-low"                # Clear female (13MB) - BMAD: Paige (tech-writer)
+)
+
+# LibriTTS voices — 904 named speakers, opt-in due to size (~114MB total)
+LIBRITTS_VOICES=(
+  "en_US-libritts-high"      # 904 named speakers — premium quality (57MB)
+  "en_US-libritts_r-medium"  # Premium male (57MB) - BMAD: BMad Master
 )
 
+# Merge libritts into the download list if requested
+if [[ "$INCLUDE_LIBRITTS" == "true" ]]; then
+  COMMON_VOICES+=("${LIBRITTS_VOICES[@]}")
+fi
+
 echo "🎙️  Piper Voice Model Downloader"
 echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
 echo ""
@@ -155,14 +178,14 @@ for voice in "${NEED_DOWNLOAD[@]}"; do
   echo "📥 Downloading: $voice..."
 
   if download_voice "$voice"; then
-    ((DOWNLOADED++))
+    DOWNLOADED=$((DOWNLOADED + 1))
     voice_path="$VOICE_DIR/${voice}.onnx"
     file_size=$(du -h "$voice_path" 2>/dev/null | cut -f1)
     echo "   ✓ Downloaded: $voice"
     echo "   📁 Path: $voice_path"
     echo "   📦 Size: $file_size"
   else
-    ((FAILED++))
+    FAILED=$((FAILED + 1))
     echo "   ✗ Failed: $voice"
   fi
 done

package/.claude/hooks/piper-installer.sh

@@ -178,9 +178,9 @@ else
 
     # Try to install pipx
     if command -v apt-get &> /dev/null; then
-      # Debian/Ubuntu
-      sudo apt-get update
-      sudo apt-get install -y pipx
+      # Debian/Ubuntu — DEBIAN_FRONTEND prevents tzdata interactive prompt
+      DEBIAN_FRONTEND=noninteractive sudo -E apt-get update -qq
+      DEBIAN_FRONTEND=noninteractive sudo -E apt-get install -y pipx
     elif command -v brew &> /dev/null; then
       # Linux with Homebrew
       brew install pipx
@@ -198,16 +198,21 @@ else
       exit 1
     fi
 
-    # Ensure pipx is in PATH
-    pipx ensurepath
+    # Ensure pipx is in PATH (updates shell rc file) and update current session
+    pipx ensurepath 2>/dev/null || true
+    export PATH="$HOME/.local/bin:$PATH"
     echo ""
   fi
 
+  # Make sure ~/.local/bin is in PATH for this session (pipx installs there)
+  export PATH="$HOME/.local/bin:$PATH"
+  INSTALL_DIR="$HOME/.local/bin"
+
   # Install Piper TTS
   echo "📥 Installing Piper TTS via pipx..."
   pipx install piper-tts
 
-  if ! command -v piper &> /dev/null; then
+  if ! command -v piper &> /dev/null && [[ ! -x "$HOME/.local/bin/piper" ]]; then
     echo ""
     echo "❌ Installation completed but piper command not found in PATH"
     echo ""

package/.claude/hooks/piper-voice-manager.sh

@@ -62,16 +62,16 @@ PIPER_VOICES_BASE_URL="https://huggingface.co/rhasspy/piper-voices/resolve/main"
 # @calledby All voice management functions (verify_voice, get_voice_path, download_voice, list_downloaded_voices)
 # @calls mkdir, cat, dirname
 get_voice_storage_dir() {
-  local voice_dir
+  local voice_dir=""
 
   # Check for custom path in environment or config file
-  if [[ -n "$PIPER_VOICES_DIR" ]]; then
-    voice_dir="$PIPER_VOICES_DIR"
+  if [[ -n "${PIPER_VOICES_DIR:-}" ]]; then
+    voice_dir="${PIPER_VOICES_DIR}"
   else
     # Check for config file (project-local first, then global)
-    local config_file
-    if [[ -n "$CLAUDE_PROJECT_DIR" ]] && [[ -f "$CLAUDE_PROJECT_DIR/.claude/piper-voices-dir.txt" ]]; then
-      config_file="$CLAUDE_PROJECT_DIR/.claude/piper-voices-dir.txt"
+    local config_file=""
+    if [[ -n "${CLAUDE_PROJECT_DIR:-}" ]] && [[ -f "${CLAUDE_PROJECT_DIR}/.claude/piper-voices-dir.txt" ]]; then
+      config_file="${CLAUDE_PROJECT_DIR}/.claude/piper-voices-dir.txt"
     else
       # Search up directory tree for .claude/
       local current_dir="$PWD"

package/.claude/hooks/play-tts-agentvibes-receiver-for-voiceless-connections.sh

@@ -98,7 +98,9 @@ echo "📱 Sending to $SSH_HOST for local playback..." >&2
 # Build SSH args — use explicit key/port from config if available, else rely on ~/.ssh/config
 SSH_ARGS=()
 [[ -n "$SSH_KEY"  && -f "$SSH_KEY"  ]] && SSH_ARGS+=(-i "$SSH_KEY")
-[[ -n "$SSH_PORT" ]] && SSH_ARGS+=(-p "$SSH_PORT")
+# Never force "-p 22" (ssh default) -- it would override an ~/.ssh/config
+# Host alias port (e.g. laptop-win -> 45217). Empty/22 => defer to ssh config.
+if [[ -n "$SSH_PORT" && "$SSH_PORT" != "22" ]]; then SSH_ARGS+=(-p "$SSH_PORT"); fi
 
 # Try receiver scripts in order — single SSH call, no separate probe
 # SECURITY: Base64-encoded values are safe to pass as arguments (no shell metacharacters)

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

@@ -0,0 +1 @@
+play-tts-agentvibes-receiver-for-voiceless-connections.sh

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

@@ -0,0 +1,360 @@
+#!/usr/bin/env bash
+#
+# File: .claude/hooks/play-tts-elevenlabs.sh
+#
+# AgentVibes - Text-to-Speech WITH personality for AI Assistants
+# Website: https://agentvibes.org
+# Repository: https://github.com/paulpreibisch/AgentVibes
+#
+# Licensed under the Apache License, Version 2.0
+#
+# @fileoverview ElevenLabs TTS Provider — cloud neural voices with 32+ language support
+# @context Provider-specific implementation for ElevenLabs API integration
+# @architecture Implements provider contract: text/voice → audio playback
+# @dependencies ELEVENLABS_API_KEY env var, curl, ffmpeg (optional), audio player
+# @entrypoints Called by play-tts.sh router when provider=elevenlabs
+# @related play-tts.sh, provider-manager.sh, language-manager.sh
+#
+# Voice can be a name (e.g. "Rachel") or a raw ElevenLabs voice ID.
+# Set ELEVENLABS_API_KEY in your shell profile or via Infisical.
+# Default voice: Rachel (English, warm female)
+#
+
+set -euo pipefail
+export LC_ALL=C
+
+TEXT="${1:-}"
+VOICE_OVERRIDE="${2:-}"
+
+# Resolve script dir (handles symlinks)
+SCRIPT_PATH="$(readlink -f "${BASH_SOURCE[0]}")"
+SCRIPT_DIR="$(dirname "$SCRIPT_PATH")"
+
+source "$SCRIPT_DIR/audio-cache-utils.sh"
+source "$SCRIPT_DIR/language-manager.sh"
+
+if [[ -z "$TEXT" ]]; then
+  echo "Usage: $0 \"text to speak\" [voice_name_or_id]" >&2
+  exit 1
+fi
+
+# Clamp text to 2000 chars (ElevenLabs API limit)
+if [[ ${#TEXT} -gt 2000 ]]; then
+  TEXT="${TEXT:0:1997}..."
+fi
+
+# ---------------------------------------------------------------------------
+# Optional: fetch the key from Infisical on demand, so no key is stored on disk.
+# Opt-in via ~/.agentvibes/infisical.env, which sets (env vars take precedence):
+#   INFISICAL_SECRET_NAME   name of the secret in Infisical (e.g. ELEVEN_LABS)
+#   INFISICAL_PROJECT_ID    project/workspace id
+#   INFISICAL_ENV           environment slug         (default: prod)
+#   INFISICAL_DOMAIN        API base URL             (default: http://127.0.0.1:8200/api)
+#   INFISICAL_BOOTSTRAP     universal-auth creds file (default: ~/.palace-bootstrap)
+# Requires the infisical CLI + python3. Fails soft: prints nothing and returns
+# non-zero when unconfigured or unreachable, so the normal error path still runs.
+# The fetched value is never printed.
+_fetch_key_from_infisical() {
+  local cfg="${HOME}/.agentvibes/infisical.env"
+  if [[ -f "$cfg" ]]; then
+    set -o allexport; source "$cfg"; set +o allexport
+  fi
+
+  local secret_name="${INFISICAL_SECRET_NAME:-}"
+  local project_id="${INFISICAL_PROJECT_ID:-}"
+  local env_name="${INFISICAL_ENV:-prod}"
+  local domain="${INFISICAL_DOMAIN:-http://127.0.0.1:8200/api}"
+  local bootstrap="${INFISICAL_BOOTSTRAP:-${HOME}/.palace-bootstrap}"
+
+  [[ -n "$secret_name" && -n "$project_id" ]] || return 1
+  command -v infisical >/dev/null 2>&1 || return 1
+  command -v python3   >/dev/null 2>&1 || return 1
+
+  # Obtain an access token: reuse an exported INFISICAL_TOKEN, else exchange the
+  # universal-auth client credentials from the bootstrap file (creds via env only).
+  local token="${INFISICAL_TOKEN:-}"
+  if [[ -z "$token" ]]; then
+    [[ -f "$bootstrap" ]] || return 1
+    set -o allexport; source "$bootstrap"; set +o allexport
+    [[ -n "${INFISICAL_UNIVERSAL_AUTH_CLIENT_ID:-}" && -n "${INFISICAL_UNIVERSAL_AUTH_CLIENT_SECRET:-}" ]] || return 1
+    token="$(_AV_DOMAIN="$domain" python3 -c '
+import os, json, urllib.request
+d = os.environ["_AV_DOMAIN"].rstrip("/")
+req = urllib.request.Request(d + "/v1/auth/universal-auth/login",
+    data=json.dumps({"clientId": os.environ["INFISICAL_UNIVERSAL_AUTH_CLIENT_ID"],
+                     "clientSecret": os.environ["INFISICAL_UNIVERSAL_AUTH_CLIENT_SECRET"]}).encode(),
+    headers={"Content-Type": "application/json"})
+print(json.loads(urllib.request.urlopen(req, timeout=10).read())["accessToken"])
+' 2>/dev/null || true)"
+  fi
+  [[ -n "$token" ]] || return 1
+
+  INFISICAL_TOKEN="$token" infisical secrets get "$secret_name" \
+    --projectId "$project_id" --env "$env_name" --domain "$domain" \
+    --plain 2>/dev/null | head -1
+}
+
+# ---------------------------------------------------------------------------
+# API key — env var (only if it looks valid), then key file, then Infisical.
+# A malformed/truncated ELEVENLABS_API_KEY (e.g. a half-pasted key) is ignored so
+# it can't silently shadow a good key file — a common foot-gun that yields
+# confusing "API key fail" errors despite a valid key on disk.
+_looks_like_el_key() {
+  [[ "$1" =~ ^sk_[A-Za-z0-9]{40,}$ ]] && return 0   # current format: sk_ + >=40 chars
+  [[ "$1" =~ ^[A-Fa-f0-9]{32}$ ]] && return 0        # legacy 32-char hex key
+  return 1
+}
+
+API_KEY=""
+if [[ -n "${ELEVENLABS_API_KEY:-}" ]]; then
+  # A non-empty env var is authoritative — ElevenLabs has shipped several key
+  # formats over time, so we must not silently discard a key just because it
+  # looks unfamiliar. Warn (using ONLY the length, never the value) if the format
+  # is unexpected, but use it regardless.
+  API_KEY="$ELEVENLABS_API_KEY"
+  if ! _looks_like_el_key "$ELEVENLABS_API_KEY"; then
+    echo "⚠️  ELEVENLABS_API_KEY env var has an unexpected format (length ${#ELEVENLABS_API_KEY}); using it anyway." >&2
+  fi
+fi
+if [[ -z "$API_KEY" ]]; then
+  _key_file="${HOME}/.agentvibes/elevenlabs-key.txt"
+  if [[ -f "$_key_file" ]]; then
+    API_KEY="$(tr -d '[:space:]' < "$_key_file")"
+  fi
+fi
+if [[ -z "$API_KEY" ]]; then
+  API_KEY="$(_fetch_key_from_infisical || true)"
+  API_KEY="$(printf '%s' "$API_KEY" | tr -d '[:space:]')"
+fi
+
+if [[ -z "$API_KEY" ]]; then
+  echo "❌ ElevenLabs API key not set." >&2
+  echo "   Set it one of three ways:" >&2
+  echo "   1. export ELEVENLABS_API_KEY=your_key  (add to ~/.bashrc or ~/.zshrc)" >&2
+  echo "   2. echo 'your_key' > ~/.agentvibes/elevenlabs-key.txt && chmod 600 ~/.agentvibes/elevenlabs-key.txt" >&2
+  echo "   3. Configure Infisical in ~/.agentvibes/infisical.env (INFISICAL_SECRET_NAME + INFISICAL_PROJECT_ID)" >&2
+  echo "   Get a free key at: https://elevenlabs.io" >&2
+  exit 2
+fi
+
+# ---------------------------------------------------------------------------
+# Inline voice name → ID map (covers common built-in ElevenLabs voices)
+declare -A VOICE_IDS
+VOICE_IDS["Rachel"]="21m00Tcm4TlvDq8ikWAM"
+VOICE_IDS["Adam"]="pNInz6obpgDQGcFmaJgB"
+VOICE_IDS["Antoni"]="ErXwobaYiN019PkySvjV"
+VOICE_IDS["Arnold"]="VR6AewLTigWG4xSOukaG"
+VOICE_IDS["Bella"]="EXAVITQu4vr4xnSDxMaL"
+VOICE_IDS["Callum"]="N2lVS1w4EtoT3dr4eOWO"
+VOICE_IDS["Charlie"]="IKne3meq5aSn9XLyUdCD"
+VOICE_IDS["Charlotte"]="XB0fDUnXU5powFXDhCwa"
+VOICE_IDS["Clyde"]="2EiwWnXFnvU5JabPnv8n"
+VOICE_IDS["Daniel"]="onwK4e9ZLuTAKqWW03F9"
+VOICE_IDS["Dave"]="CYw3kZ02Hs0563khs1Fj"
+VOICE_IDS["Dorothy"]="ThT5KcBeYPX3keUQqHPh"
+VOICE_IDS["Domi"]="AZnzlk1XvdvUeBnXmlld"
+VOICE_IDS["Drew"]="29vD33N1CtxCmqQRPOHJ"
+VOICE_IDS["Emily"]="LcfcDJNUP1GQjkzn1xUU"
+VOICE_IDS["Ethan"]="g5CIjZEefAph4nQFvHAz"
+VOICE_IDS["Fin"]="D38z5RcWu1voky8WS1ja"
+VOICE_IDS["Freya"]="jsCqWAovK2LkecY7zXl4"
+VOICE_IDS["Gigi"]="jBpfuIE2acCO8z3wKNLl"
+VOICE_IDS["Giovanni"]="zcAOhNBS3c14rBihAFp1"
+VOICE_IDS["Glinda"]="z9fAnlkpzviPz146aGWa"
+VOICE_IDS["Grace"]="oWAxZDx7w5VEj9dCyTzz"
+VOICE_IDS["Harry"]="SOYHLrjzK2X1ezoPC6cr"
+VOICE_IDS["James"]="ZQe5CZNOzWyzPSCn5a3c"
+VOICE_IDS["Jessie"]="t0jbNlBVZ17f02VDIeMI"
+VOICE_IDS["Josh"]="TxGEqnHWrfWFTfGW9XjX"
+VOICE_IDS["Liam"]="TX3LPaxmHKxFdv7VOQHJ"
+VOICE_IDS["Lily"]="pFZP5JQG7iQjIQuC4Bku"
+VOICE_IDS["Matilda"]="XrExE9yKIg1WjnnlVkGX"
+VOICE_IDS["Michael"]="flq6f7yk4E4fJM5XTYuZ"
+VOICE_IDS["Mimi"]="zrHiDhphv9ZnVXBqCLjz"
+VOICE_IDS["Nicole"]="piTKgcLEGmPE4e6mEKli"
+VOICE_IDS["Patrick"]="ODq5zmih8GrVes37Dizd"
+VOICE_IDS["Paul"]="5Q0t7uMcjvnagumLfvZi"
+VOICE_IDS["Sam"]="yoZ06aMxZJJ28mfd3POQ"
+VOICE_IDS["Sarah"]="EXAVITQu4vr4xnSDxMaL"
+VOICE_IDS["Serena"]="pMsXgVXv3BLzUgSXRplE"
+VOICE_IDS["Thomas"]="GBv7mTt0atIp3Br8iCZE"
+
+DEFAULT_VOICE_ID="${VOICE_IDS[Rachel]}"
+
+# ---------------------------------------------------------------------------
+# Resolve voice ID from override or config
+VOICE_ID=""
+
+if [[ -n "$VOICE_OVERRIDE" ]]; then
+  if [[ -n "${VOICE_IDS[$VOICE_OVERRIDE]:-}" ]]; then
+    VOICE_ID="${VOICE_IDS[$VOICE_OVERRIDE]}"
+  elif [[ "$VOICE_OVERRIDE" =~ ^[a-zA-Z0-9]{10,40}$ ]]; then
+    # Looks like a raw voice ID
+    VOICE_ID="$VOICE_OVERRIDE"
+  else
+    echo "⚠️  Unknown ElevenLabs voice '$VOICE_OVERRIDE', using Rachel" >&2
+    VOICE_ID="$DEFAULT_VOICE_ID"
+  fi
+else
+  # Check voice manager for configured voice
+  VOICE_NAME=""
+  if [[ -f "$SCRIPT_DIR/voice-manager.sh" ]]; then
+    VOICE_NAME="$("$SCRIPT_DIR/voice-manager.sh" get 2>/dev/null || true)"
+  fi
+
+  if [[ -n "$VOICE_NAME" && -n "${VOICE_IDS[$VOICE_NAME]:-}" ]]; then
+    VOICE_ID="${VOICE_IDS[$VOICE_NAME]}"
+  else
+    VOICE_ID="$DEFAULT_VOICE_ID"
+  fi
+fi
+
+# ---------------------------------------------------------------------------
+# Language/model selection
+CURRENT_LANGUAGE="$(get_language_code 2>/dev/null || echo 'english')"
+
+case "$CURRENT_LANGUAGE" in
+  english) LANGUAGE_CODE="en"; MODEL_ID="eleven_turbo_v2_5" ;;
+  spanish) LANGUAGE_CODE="es"; MODEL_ID="eleven_multilingual_v2" ;;
+  french)  LANGUAGE_CODE="fr"; MODEL_ID="eleven_multilingual_v2" ;;
+  german)  LANGUAGE_CODE="de"; MODEL_ID="eleven_multilingual_v2" ;;
+  italian) LANGUAGE_CODE="it"; MODEL_ID="eleven_multilingual_v2" ;;
+  portuguese) LANGUAGE_CODE="pt"; MODEL_ID="eleven_multilingual_v2" ;;
+  chinese) LANGUAGE_CODE="zh"; MODEL_ID="eleven_multilingual_v2" ;;
+  japanese) LANGUAGE_CODE="ja"; MODEL_ID="eleven_multilingual_v2" ;;
+  korean)  LANGUAGE_CODE="ko"; MODEL_ID="eleven_multilingual_v2" ;;
+  russian) LANGUAGE_CODE="ru"; MODEL_ID="eleven_multilingual_v2" ;;
+  polish)  LANGUAGE_CODE="pl"; MODEL_ID="eleven_multilingual_v2" ;;
+  dutch)   LANGUAGE_CODE="nl"; MODEL_ID="eleven_multilingual_v2" ;;
+  arabic)  LANGUAGE_CODE="ar"; MODEL_ID="eleven_multilingual_v2" ;;
+  hindi)   LANGUAGE_CODE="hi"; MODEL_ID="eleven_multilingual_v2" ;;
+  turkish) LANGUAGE_CODE="tr"; MODEL_ID="eleven_multilingual_v2" ;;
+  swedish) LANGUAGE_CODE="sv"; MODEL_ID="eleven_multilingual_v2" ;;
+  *)       LANGUAGE_CODE="en"; MODEL_ID="eleven_turbo_v2_5" ;;
+esac
+
+# ---------------------------------------------------------------------------
+# Audio output directory
+AUDIO_DIR="$(get_audio_cache_dir 2>/dev/null || echo "${HOME}/.claude/audio")"
+mkdir -p "$AUDIO_DIR"
+chmod 700 "$AUDIO_DIR"
+
+TEMP_FILE="${AUDIO_DIR}/tts-elevenlabs-$(date +%s%N | head -c 18).mp3"
+BODY_FILE="${AUDIO_DIR}/tts-el-body-$(date +%s%N | head -c 18).json"
+trap 'rm -f "${TEMP_FILE:-}" "${BODY_FILE:-}" 2>/dev/null || true' EXIT
+
+# ---------------------------------------------------------------------------
+# Build the JSON request body with python so all escaping is handled correctly
+# (text is passed via env, never interpolated into a shell-quoted payload).
+if ! TTS_TEXT="$TEXT" TTS_MODEL="$MODEL_ID" TTS_LANG="$LANGUAGE_CODE" python3 -c '
+import os, json
+print(json.dumps({
+    "text": os.environ["TTS_TEXT"],
+    "model_id": os.environ["TTS_MODEL"],
+    "language_code": os.environ["TTS_LANG"],
+    "voice_settings": {"stability": 0.5, "similarity_boost": 0.75},
+}))' > "$BODY_FILE" 2>/dev/null; then
+  echo "❌ Failed to build ElevenLabs request body (python3 required)" >&2
+  exit 3
+fi
+
+# ---------------------------------------------------------------------------
+# Test mode: never make a billable request to the ElevenLabs API (and never play
+# audio). Short-circuit BEFORE the network call. Mirrors the sibling providers'
+# AGENTVIBES_TEST_MODE handling; the EXIT trap cleans up the temp files.
+if [[ "${AGENTVIBES_TEST_MODE:-false}" == "true" ]]; then
+  exit 0
+fi
+
+# ---------------------------------------------------------------------------
+# Call ElevenLabs API
+# Security: API key passed via a curl config read from stdin (-K -), so it never
+# appears in argv (where `ps` could expose it) nor in any temp file.
+HTTP_STATUS=$(printf 'header = "xi-api-key: %s"\n' "$API_KEY" | curl -s -o "$TEMP_FILE" -w "%{http_code}" \
+  -X POST "https://api.elevenlabs.io/v1/text-to-speech/${VOICE_ID}" \
+  -K - \
+  -H "Content-Type: application/json" \
+  --max-time 30 \
+  --data-binary "@${BODY_FILE}" 2>&1)
+rm -f "$BODY_FILE" 2>/dev/null || true
+
+if [[ "$HTTP_STATUS" != "200" ]]; then
+  echo "❌ ElevenLabs API error (HTTP $HTTP_STATUS)" >&2
+  if [[ -f "$TEMP_FILE" ]]; then
+    cat "$TEMP_FILE" >&2
+  fi
+  exit 3
+fi
+
+if [[ ! -f "$TEMP_FILE" || ! -s "$TEMP_FILE" ]]; then
+  echo "❌ ElevenLabs returned empty audio" >&2
+  exit 3
+fi
+
+# ---------------------------------------------------------------------------
+# Convert MP3 → WAV so the post-processor (sox effects) can read it, and add a
+# short silence lead-in (prevents a clipped first phoneme / WSL audio static).
+# ffmpeg is preferred; if it is absent we keep the MP3 and skip effects/music.
+if command -v ffmpeg &>/dev/null; then
+  _WAV="${AUDIO_DIR}/tts-el-$(date +%s%N | head -c 18).wav"
+  trap 'rm -f "${TEMP_FILE:-}" "${_WAV:-}" 2>/dev/null || true' EXIT
+  if ffmpeg -f lavfi -i "anullsrc=r=44100:cl=mono:d=0.15" -i "$TEMP_FILE" \
+      -filter_complex "[0:a][1:a]concat=n=2:v=0:a=1[out]" \
+      -map "[out]" -ar 44100 -ac 1 -y "$_WAV" 2>/dev/null \
+      && [[ -s "$_WAV" ]]; then
+    rm -f "$TEMP_FILE"
+    TEMP_FILE="$_WAV"
+  fi
+fi
+
+# ---------------------------------------------------------------------------
+# Post-process: apply audio effects (reverb/echo/chorus via sox) and mix
+# background music (via ffmpeg) — exactly like the Piper provider does. Honors
+# the per-LLM row (AGENTVIBES_LLM_KEY) and any per-call AGENTVIBES_REVERB_OVERRIDE.
+# Fails soft: if audio-processor.sh or its tools (sox/ffmpeg) are missing, the
+# unprocessed audio is played instead. NOTE: reverb/echo/chorus REQUIRE sox to be
+# installed; without it, effects are silently skipped (background music still works
+# via ffmpeg).
+#
+# Only post-process when invoked via the orchestrator (which exports
+# AGENTVIBES_LLM_KEY) or with an explicit per-call effect override. A bare direct
+# call — e.g. the voice-picker audition — gets the clean, dry voice so the user
+# hears the voice itself, not the default LLM row's effects/music.
+if [[ -f "$SCRIPT_DIR/audio-processor.sh" \
+      && ( -n "${AGENTVIBES_LLM_KEY:-}" || -n "${AGENTVIBES_REVERB_OVERRIDE:-}" ) ]]; then
+  _PROCESSED="${AUDIO_DIR}/tts-el-proc-$(date +%s%N | head -c 18).wav"
+  trap 'rm -f "${TEMP_FILE:-}" "${_PROCESSED:-}" 2>/dev/null || true' EXIT
+  _AGENT_KEY="${AGENTVIBES_LLM_KEY:-default}"
+  if _PROC_OUT="$(bash "$SCRIPT_DIR/audio-processor.sh" "$TEMP_FILE" "$_AGENT_KEY" "$_PROCESSED" 2>/dev/null)"; then
+    _PF="${_PROC_OUT%%|*}"
+    if [[ -n "$_PF" && -f "$_PF" && -s "$_PF" && "$_PF" != "$TEMP_FILE" ]]; then
+      rm -f "$TEMP_FILE"
+      TEMP_FILE="$_PF"
+    fi
+  fi
+fi
+
+# Play audio (skip in test mode or no-playback mode — matches the Piper provider)
+# AGENTVIBES_NO_PLAYBACK: Set to "true" to generate audio without playing (for post-processing)
+# Native Windows (git-bash, OS=Windows_NT — not WSL) has none of the Linux
+# players, and ffplay spawned from the TUI's Node process is unreliable. Use the
+# built-in PowerShell WPF MediaPlayer (same as audio-env.js) — no ffmpeg/PATH
+# dependency. Other platforms try the usual players.
+if [[ "${AGENTVIBES_TEST_MODE:-false}" != "true" ]] && [[ "${AGENTVIBES_NO_PLAYBACK:-false}" != "true" ]]; then
+  _PS_BIN="$(command -v powershell 2>/dev/null || command -v powershell.exe 2>/dev/null || true)"
+  if [[ "${OS:-}" == "Windows_NT" && -n "$_PS_BIN" ]]; then
+    _WINPATH="$(cygpath -w "$TEMP_FILE" 2>/dev/null || echo "$TEMP_FILE")"
+    _WINPATH="${_WINPATH//\'/\'\'}"   # escape single quotes for the PowerShell literal
+    "$_PS_BIN" -NoProfile -Command "Add-Type -AssemblyName PresentationCore; \$p = New-Object System.Windows.Media.MediaPlayer; \$p.Open([uri]'${_WINPATH}'); \$p.Play(); Start-Sleep -Milliseconds 300; \$last=[TimeSpan]::Zero; \$stall=0; \$n=0; while (\$n -lt 100) { Start-Sleep -Milliseconds 100; \$pos=\$p.Position; if (\$p.NaturalDuration.HasTimeSpan -and \$pos -ge \$p.NaturalDuration.TimeSpan) { break }; if (\$pos -eq \$last) { \$stall++ } else { \$stall=0 }; if (\$stall -ge 8 -and \$pos -gt [TimeSpan]::Zero) { break }; \$last=\$pos; \$n++ }; \$p.Stop(); \$p.Close()" 2>/dev/null || true
+  else
+    (paplay "$TEMP_FILE" 2>/dev/null \
+      || aplay "$TEMP_FILE" 2>/dev/null \
+      || mpg123 -q "$TEMP_FILE" 2>/dev/null \
+      || ffplay -nodisp -autoexit -loglevel error "$TEMP_FILE" 2>/dev/null \
+      || true) &
+    wait $!
+  fi
+fi
+
+# Cancel trap so file persists in cache (for replay)
+trap '' EXIT

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

@@ -0,0 +1,127 @@
+#!/usr/bin/env bash
+#
+# File: .claude/hooks/play-tts-kokoro.sh
+#
+# AgentVibes - Text-to-Speech WITH personality for AI Assistants
+# Website: https://agentvibes.org
+# Repository: https://github.com/paulpreibisch/AgentVibes
+#
+# Licensed under the Apache License, Version 2.0
+#
+# @fileoverview Kokoro TTS Provider — 82M-param local neural TTS, 60+ voices, 8+ languages
+# @context Provides high-quality local TTS via kokoro-onnx (MIT license, no API key needed)
+# @architecture Implements provider contract: text/voice → audio playback
+# @dependencies kokoro-onnx, soundfile, numpy (pip), ffmpeg (optional), audio player
+# @entrypoints Called by play-tts.sh router when provider=kokoro
+# @related play-tts.sh, kokoro-installer.sh, kokoro-tts.py
+#
+# Default voice: af_heart (American Female, warm)
+# Install: /home/user/.claude/hooks/kokoro-installer.sh
+# Or manually: pip install kokoro-onnx soundfile numpy
+#
+
+set -euo pipefail
+export LC_ALL=C
+
+TEXT="${1:-}"
+VOICE_OVERRIDE="${2:-}"
+
+# Resolve script dir (handles symlinks)
+SCRIPT_PATH="$(readlink -f "${BASH_SOURCE[0]}")"
+SCRIPT_DIR="$(dirname "$SCRIPT_PATH")"
+
+source "$SCRIPT_DIR/audio-cache-utils.sh"
+
+if [[ -z "$TEXT" ]]; then
+  echo "Usage: $0 \"text to speak\" [voice]" >&2
+  exit 1
+fi
+
+# Check kokoro is installed (use find_spec to avoid slow torch import)
+if ! python3 -c "import importlib.util; exit(0 if importlib.util.find_spec('kokoro') else 1)" 2>/dev/null; then
+  echo "❌ Kokoro TTS not installed." >&2
+  echo "   Install with: ${SCRIPT_DIR}/kokoro-installer.sh" >&2
+  echo "   Or manually:  pip install kokoro-onnx soundfile numpy" >&2
+  exit 2
+fi
+
+# ---------------------------------------------------------------------------
+# Resolve voice
+DEFAULT_VOICE="af_heart"
+
+if [[ -n "$VOICE_OVERRIDE" ]]; then
+  # Accept kokoro-style voice IDs (2-letter prefix + underscore + name)
+  # e.g. af_heart, am_adam, bf_emma, bm_george
+  if [[ "$VOICE_OVERRIDE" =~ ^[a-z]{2}_[a-z0-9_]+$ ]]; then
+    VOICE="$VOICE_OVERRIDE"
+  else
+    echo "⚠️  Unrecognized kokoro voice '$VOICE_OVERRIDE', using $DEFAULT_VOICE" >&2
+    VOICE="$DEFAULT_VOICE"
+  fi
+else
+  # Check voice manager
+  if [[ -f "$SCRIPT_DIR/voice-manager.sh" ]]; then
+    _CONFIGURED="$("$SCRIPT_DIR/voice-manager.sh" get 2>/dev/null || true)"
+    if [[ "$_CONFIGURED" =~ ^[a-z]{2}_[a-z0-9_]+$ ]]; then
+      VOICE="$_CONFIGURED"
+    else
+      VOICE="$DEFAULT_VOICE"
+    fi
+  else
+    VOICE="$DEFAULT_VOICE"
+  fi
+fi
+
+# Speed from config (optional, defaults to 1.0)
+# SECURITY: Validate speed is numeric before passing to python (avoids traceback)
+SPEED="${KOKORO_SPEED:-1.0}"
+[[ "$SPEED" =~ ^[0-9]+(\.[0-9]+)?$ ]] || SPEED="1.0"
+
+# ---------------------------------------------------------------------------
+# Synthesis
+AUDIO_DIR="$(get_audio_cache_dir 2>/dev/null || echo "${HOME}/.claude/audio")"
+mkdir -p "$AUDIO_DIR"
+chmod 700 "$AUDIO_DIR"
+
+TEMP_WAV="${AUDIO_DIR}/tts-kokoro-$(date +%s%N | head -c 18).wav"
+trap 'rm -f "${TEMP_WAV:-}" 2>/dev/null || true' EXIT
+
+SYNTH_SCRIPT="${SCRIPT_DIR}/kokoro-tts.py"
+if [[ ! -f "$SYNTH_SCRIPT" ]]; then
+  echo "❌ kokoro-tts.py not found at $SYNTH_SCRIPT" >&2
+  exit 2
+fi
+
+# Skip the (slow) synthesis + playback entirely in test mode — nothing to play
+# and no need to spin up the kokoro model. Mirrors the sibling Piper provider.
+if [[ "${AGENTVIBES_TEST_MODE:-false}" == "true" ]]; then
+  trap '' EXIT
+  exit 0
+fi
+
+# Run synthesis — output path printed to stdout
+RESULT=$(python3 "$SYNTH_SCRIPT" "$TEXT" "$VOICE" "$TEMP_WAV" "$SPEED" 2>&1) || {
+  echo "❌ Kokoro synthesis failed: $RESULT" >&2
+  exit 3
+}
+
+if [[ ! -f "$TEMP_WAV" || ! -s "$TEMP_WAV" ]]; then
+  echo "❌ Kokoro synthesis produced no audio" >&2
+  exit 3
+fi
+
+# ---------------------------------------------------------------------------
+# Play audio — try players in order (WAV-capable)
+# Skip playback in test mode or no-playback mode (matches the Piper provider).
+# AGENTVIBES_NO_PLAYBACK: Set to "true" to generate audio without playing (for post-processing)
+if [[ "${AGENTVIBES_TEST_MODE:-false}" != "true" ]] && [[ "${AGENTVIBES_NO_PLAYBACK:-false}" != "true" ]]; then
+  (aplay -q "$TEMP_WAV" 2>/dev/null \
+    || paplay "$TEMP_WAV" 2>/dev/null \
+    || ffplay -nodisp -autoexit -loglevel quiet "$TEMP_WAV" 2>/dev/null \
+    || mpg123 -q "$TEMP_WAV" 2>/dev/null \
+    || true) &
+  wait $!
+fi
+
+# Cancel trap so file persists in cache
+trap '' EXIT