agentvibes 5.6.8 → 5.6.9

package/.agentvibes/config/README-personality-defaults.md

@@ -0,0 +1,162 @@
+# Personality Voice Defaults
+
+## What is this?
+
+This configuration file (`personality-voice-defaults.json`) maps each AgentVibes personality to a specific Piper TTS voice that sounds best for that character.
+
+## How it works for new users
+
+When someone installs AgentVibes with Piper TTS:
+
+### 1. Installation Process
+
+```bash
+# User installs Piper
+.claude/hooks/piper-installer.sh
+```
+
+**What happens:**
+- Piper TTS binary gets installed via `pipx`
+- User is asked: "Download voice models now?"
+- If yes, runs `piper-download-voices.sh` which downloads:
+  - **16Speakers** (~25MB) - Multi-voice model with 16 speakers
+  - **en_GB-alan-medium** (~25MB) - British male voice
+  - **en_GB-semaine-medium** (~25MB) - British female voice
+  - Plus a few other standard voices
+- Default personality mappings are installed automatically
+
+### 2. What gets downloaded
+
+**Required voices for personality defaults:**
+- ✅ **16Speakers** (1 file) - Provides 16 different speakers:
+  - #0: Cori Samuel (female) - Used for: flirty, dramatic, dry_humor, sassy
+  - #2: Kristin Hughes (female) - Used for: poetic, sarcastic
+  - #4: Mike Pelton (male) - Used for: grandpa
+  - #8: Rose Ibex (female) - Used for: moody
+  - #13: Jennifer Dorr (female) - Used for: millennial
+  - #14: Emily Cripps (female) - Used for: zen
+  - #15: Martin Clifton (male) - Used for: pirate
+
+- ✅ **en_GB-alan-medium** - British male voice
+  - Used for: angry, professional, surfer_dude
+
+- ✅ **en_GB-semaine-medium** - British female voice
+  - Used for: funny
+
+**Total download size: ~75MB** (3 voice models)
+
+### 3. First time using a personality
+
+```bash
+# User switches personality
+/agent-vibes:personality flirty
+```
+
+**What happens:**
+1. AgentVibes reads `personality-voice-defaults.json`
+2. Finds that "flirty" → "16Speakers#0" (Cori Samuel)
+3. Checks if 16Speakers is downloaded
+4. **If not downloaded:**
+   - Prompts: "Voice model not found: 16Speakers. Download? [y/N]"
+   - User says yes → Downloads automatically from HuggingFace
+   - Only happens once per voice model
+5. **If already downloaded:**
+   - Switches to the voice immediately
+   - Plays personality-appropriate TTS
+
+### 4. Graceful fallbacks
+
+If a user:
+- Skips voice downloads during install → On-demand download when needed
+- Deletes the defaults file → Falls back to basic `en_US-lessac-medium`
+- Uses a personality without a mapping → Uses default voice
+
+## For power users
+
+### Customizing defaults
+
+Edit `.claude/personality-voice-defaults.json`:
+
+```json
+{
+  "mappings": {
+    "flirty": {
+      "voice": "16Speakers#0",
+      "rating": 10,
+      "display_name": "Cori Samuel"
+    }
+  }
+}
+```
+
+Change the `voice` field to any Piper voice name.
+
+### Using the voice tester
+
+1. Run the voice tester (in `voice-tester/` folder)
+2. Rate voices for each personality
+3. Export ratings as JSON
+4. Import with: `./import-voice-ratings.sh my-ratings.json`
+
+### Available voices
+
+List all Piper voices: https://huggingface.co/rhasspy/piper-voices
+
+Any voice can be used - AgentVibes will download it on first use.
+
+## FAQ
+
+**Q: Do new users need to download all voices upfront?**
+A: No! Only 3 files (~75MB total) are recommended. Others download on-demand.
+
+**Q: What if a user doesn't download any voices?**
+A: First personality switch will prompt to download the needed voice.
+
+**Q: Can users change the defaults?**
+A: Yes! Edit the JSON file or use the voice tester to rate and export new preferences.
+
+**Q: What if 16Speakers isn't available?**
+A: It's hosted on AgentVibes HuggingFace and included in the download script.
+
+**Q: What happens on slow connections?**
+A: Each voice is ~25MB. Downloads are one-time only and optional.
+
+## Architecture
+
+```
+Installation Flow:
+1. User runs piper-installer.sh
+   ↓
+2. Piper binary installed via pipx
+   ↓
+3. Ask: "Download voices?" → Yes
+   ↓
+4. piper-download-voices.sh runs
+   - Downloads 16Speakers (custom, HuggingFace)
+   - Downloads en_GB-alan-medium (official Piper)
+   - Downloads en_GB-semaine-medium (official Piper)
+   - Downloads other optional voices
+   ↓
+5. install-personality-defaults.sh runs
+   - Copies personality-voice-defaults.json to user config
+   ↓
+6. Ready! Personalities now auto-select best voices
+
+Runtime Flow:
+User: /agent-vibes:personality flirty
+   ↓
+personality-manager.sh checks:
+   1. User defaults (.claude/personality-voice-defaults.json)
+   2. Personality file (piper_voice: field)
+   3. Global default (en_US-lessac-medium)
+   ↓
+Found: 16Speakers#0
+   ↓
+Check if downloaded → Yes
+   ↓
+Switch to voice & play TTS!
+```
+
+## Credits
+
+Voice selections curated by Paul Preibisch based on extensive testing with the AgentVibes voice tester (16 personalities × 19 voices).

package/.agentvibes/config/agentvibes.json

@@ -0,0 +1 @@
+{"pretext": "AgentVibes"}

package/.agentvibes/config/mode.txt

@@ -0,0 +1 @@
+full

package/.agentvibes/config/personality-voice-defaults.default.json

@@ -0,0 +1,21 @@
+{
+  "version": "1.0",
+  "description": "Default Piper voice assignments for each personality",
+  "mappings": {
+    "angry": {"voice": "en_GB-alan-medium", "rating": 10, "display_name": "English GB - Alan"},
+    "dramatic": {"voice": "16Speakers#0", "rating": 10, "display_name": "Cori Samuel"},
+    "dry_humor": {"voice": "16Speakers#0", "rating": 10, "display_name": "Cori Samuel"},
+    "flirty": {"voice": "16Speakers#0", "rating": 10, "display_name": "Cori Samuel"},
+    "funny": {"voice": "en_GB-semaine-medium", "rating": 10, "display_name": "English GB - Semaine"},
+    "grandpa": {"voice": "16Speakers#4", "rating": 10, "display_name": "Mike Pelton"},
+    "millennial": {"voice": "16Speakers#13", "rating": 10, "display_name": "Jennifer Dorr"},
+    "moody": {"voice": "16Speakers#8", "rating": 10, "display_name": "Rose Ibex"},
+    "pirate": {"voice": "16Speakers#15", "rating": 10, "display_name": "Martin Clifton"},
+    "poetic": {"voice": "16Speakers#2", "rating": 10, "display_name": "Kristin Hughes"},
+    "professional": {"voice": "en_GB-alan-medium", "rating": 10, "display_name": "English GB - Alan"},
+    "sarcastic": {"voice": "16Speakers#2", "rating": 10, "display_name": "Kristin Hughes"},
+    "sassy": {"voice": "16Speakers#0", "rating": 10, "display_name": "Cori Samuel"},
+    "surfer_dude": {"voice": "en_GB-alan-medium", "rating": 10, "display_name": "English GB - Alan"},
+    "zen": {"voice": "16Speakers#14", "rating": 10, "display_name": "Emily Cripps"}
+  }
+}

package/.agentvibes/config/save-audio.txt

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

package/.agentvibes/config/voice-metadata.json

@@ -0,0 +1,160 @@
+{
+  "version": "1.0.0",
+  "provider": "piper",
+  "voices": {
+    "ryan": {
+      "id": "en_US-ryan-high",
+      "displayName": "Ryan",
+      "gender": "male",
+      "accent": "American",
+      "region": "US",
+      "quality": "high",
+      "sampleRate": "22050Hz",
+      "personality": ["professional", "clear", "confident", "authoritative"],
+      "recommendedFor": ["business", "technical", "presentations", "narrator"],
+      "description": "Professional American male voice with clear articulation",
+      "sampleFile": "ryan.wav"
+    },
+    "joe": {
+      "id": "en_US-joe-medium",
+      "displayName": "Joe",
+      "gender": "male",
+      "accent": "American",
+      "region": "US",
+      "quality": "medium",
+      "sampleRate": "22050Hz",
+      "personality": ["warm", "friendly", "casual", "approachable"],
+      "recommendedFor": ["casual", "friendly", "conversational", "assistant"],
+      "description": "Warm and friendly American male voice",
+      "sampleFile": "joe.wav"
+    },
+    "alan": {
+      "id": "en_GB-alan-medium",
+      "displayName": "Alan",
+      "gender": "male",
+      "accent": "British",
+      "region": "GB",
+      "quality": "medium",
+      "sampleRate": "22050Hz",
+      "personality": ["refined", "sophisticated", "intelligent", "articulate"],
+      "recommendedFor": ["formal", "educational", "architect", "expert"],
+      "description": "Refined British male voice with sophisticated tone",
+      "sampleFile": "alan.wav"
+    },
+    "marcus": {
+      "id": "en_US-kusal-medium",
+      "displayName": "Marcus",
+      "gender": "male",
+      "accent": "American",
+      "region": "US",
+      "quality": "medium",
+      "sampleRate": "22050Hz",
+      "personality": ["steady", "reliable", "focused", "analytical"],
+      "recommendedFor": ["testing", "QA", "technical", "documentation"],
+      "description": "Steady and reliable American male voice",
+      "sampleFile": "marcus.wav"
+    },
+    "john": {
+      "id": "en_US-john-medium",
+      "displayName": "John",
+      "gender": "male",
+      "accent": "American",
+      "region": "US",
+      "quality": "medium",
+      "sampleRate": "22050Hz",
+      "personality": ["energetic", "enthusiastic", "engaging", "dynamic"],
+      "recommendedFor": ["product-management", "leadership", "motivational", "presentations"],
+      "description": "Energetic and enthusiastic American male voice",
+      "sampleFile": "john.wav"
+    },
+    "katherine": {
+      "id": "en_US-lessac-high",
+      "displayName": "Katherine",
+      "gender": "female",
+      "accent": "American",
+      "region": "US",
+      "quality": "high",
+      "sampleRate": "22050Hz",
+      "personality": ["professional", "articulate", "polished", "executive"],
+      "recommendedFor": ["business", "executive", "formal", "professional"],
+      "description": "Professional American female voice with executive presence",
+      "sampleFile": "katherine.wav"
+    },
+    "linda": {
+      "id": "en_US-ljspeech-high",
+      "displayName": "Linda",
+      "gender": "female",
+      "accent": "American",
+      "region": "US",
+      "quality": "high",
+      "sampleRate": "22050Hz",
+      "personality": ["clear", "neutral", "precise", "informative"],
+      "recommendedFor": ["narrator", "audiobooks", "educational", "news"],
+      "description": "Clear and precise American female narrator voice",
+      "sampleFile": "linda.wav"
+    },
+    "amy": {
+      "id": "en_US-amy-medium",
+      "displayName": "Amy",
+      "gender": "female",
+      "accent": "American",
+      "region": "US",
+      "quality": "medium",
+      "sampleRate": "22050Hz",
+      "personality": ["friendly", "approachable", "helpful", "cheerful"],
+      "recommendedFor": ["assistant", "notifications", "casual", "friendly"],
+      "description": "Friendly and approachable American female voice",
+      "sampleFile": "amy.wav"
+    },
+    "kristin": {
+      "id": "en_US-kristin-medium",
+      "displayName": "Kristin",
+      "gender": "female",
+      "accent": "American",
+      "region": "US",
+      "quality": "medium",
+      "sampleRate": "22050Hz",
+      "personality": ["analytical", "thoughtful", "intelligent", "insightful"],
+      "recommendedFor": ["analyst", "research", "strategy", "consulting"],
+      "description": "Thoughtful and analytical American female voice",
+      "sampleFile": "kristin.wav"
+    },
+    "charlotte": {
+      "id": "en_GB-southern_english_female-low",
+      "displayName": "Charlotte",
+      "gender": "female",
+      "accent": "British",
+      "region": "GB",
+      "quality": "low",
+      "sampleRate": "16000Hz",
+      "personality": ["elegant", "sophisticated", "cultured", "refined"],
+      "recommendedFor": ["formal", "sophisticated", "cultural", "narrator"],
+      "description": "Elegant British female voice with southern English accent",
+      "sampleFile": "charlotte.wav"
+    }
+  },
+  "defaultVoice": "ryan",
+  "installerVoices": [
+    "ryan",
+    "joe",
+    "alan",
+    "marcus",
+    "john",
+    "katherine",
+    "linda",
+    "amy",
+    "kristin",
+    "charlotte"
+  ],
+  "bmadAgentDefaults": {
+    "architect": "alan",
+    "analyst": "kristin",
+    "dev": "joe",
+    "pm": "john",
+    "sm": "amy",
+    "tea": "marcus",
+    "tech-writer": "linda",
+    "ux-designer": "charlotte",
+    "bmad-master": "ryan"
+  }
+}

package/.agentvibes/config.json

@@ -1,3 +1,40 @@
 {
-  "setupCompleted": true
+  "defaultVoice": "libritts-speaker-925",
+  "ttsProvider": "piper",
+  "provider": "soprano",
+  "backgroundMusic": {
+    "enabled": false,
+    "track": "agent_vibes_japanese_city_pop_v1_loop.mp3",
+    "volume": 20
+  },
+  "music": {
+    "enabled": true,
+    "track": "agentvibes_nature_sounds_rain.mp3"
+  },
+  "musicFavorites": [
+    "agentvibes_blues_smooth_guitar.mp3",
+    "agentvibes_lofi_beats_coding.mp3",
+    "agentvibes_nature_sounds_rain.mp3",
+    "agent_vibes_ganawa_ambient_v2_loop.mp3"
+  ],
+  "effects": {
+    "reverb": true,
+    "reverbAmount": 0.6,
+    "pitch": 2,
+    "reverbPreset": "medium"
+  },
+  "verbosity": "high",
+  "personality": "grandpa",
+  "voice": "16Speakers::Cori_Samuel",
+  "pretext": "Agent Vibes Here",
+  "setupCompleted": true,
+  "ttsEngine": "piper",
+  "thumbsUp": [
+    "en_US-libritts-high::Adam",
+    "en_US-libritts_r-medium::Adam-2"
+  ],
+  "favorites": [
+    "en_US-libritts-high::Adam",
+    "en_US-libritts_r-medium::Adam-2"
+  ]
 }

package/.agentvibes/hooks/help.sh

@@ -0,0 +1,191 @@
+#!/usr/bin/env bash
+#
+# File: .agentvibes/hooks/help.sh
+#
+# AgentVibes Help & Diagnostic Tool
+# User-friendly status check with actionable suggestions
+#
+
+set -euo pipefail
+
+# Fix locale warnings
+export LC_ALL=C
+
+# Directories
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+AGENTVIBES_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+CLAUDE_DIR=".claude"
+CONFIG_DIR="$AGENTVIBES_DIR/config"
+
+# Files
+MODE_FILE="$CONFIG_DIR/mode.txt"
+SESSION_START_HOOK="$CLAUDE_DIR/hooks/session-start-tts.sh"
+POST_TOOL_USE_HOOK="$CLAUDE_DIR/hooks/post-tool-use.sh"
+PLAY_TTS_SCRIPT="$CLAUDE_DIR/hooks/play-tts.sh"
+
+# Colors
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+RED='\033[0;31m'
+BLUE='\033[0;34m'
+GRAY='\033[0;90m'
+NC='\033[0m' # No Color
+
+# Get current mode
+get_current_mode() {
+  if [[ -f "$MODE_FILE" ]]; then
+    cat "$MODE_FILE"
+  else
+    echo "full"
+  fi
+}
+
+# Get current voice
+get_current_voice() {
+  if [[ -f ".claude/tts-voice.txt" ]]; then
+    cat ".claude/tts-voice.txt"
+  elif [[ -f "$HOME/.claude/tts-voice.txt" ]]; then
+    cat "$HOME/.claude/tts-voice.txt"
+  else
+    echo "Default"
+  fi
+}
+
+# Get current provider
+get_current_provider() {
+  if [[ -f ".claude/tts-provider.txt" ]]; then
+    cat ".claude/tts-provider.txt"
+  elif [[ -f "$HOME/.claude/tts-provider.txt" ]]; then
+    cat "$HOME/.claude/tts-provider.txt"
+  else
+    echo "piper"
+  fi
+}
+
+# Get current verbosity
+get_current_verbosity() {
+  if [[ -f ".claude/tts-verbosity.txt" ]]; then
+    cat ".claude/tts-verbosity.txt"
+  elif [[ -f "$HOME/.claude/tts-verbosity.txt" ]]; then
+    cat "$HOME/.claude/tts-verbosity.txt"
+  else
+    echo "high"
+  fi
+}
+
+# Check if muted
+is_muted() {
+  if [[ -f "$HOME/.agentvibes-muted" ]] || [[ -f ".claude/agentvibes-muted" ]]; then
+    return 0  # True - is muted
+  else
+    return 1  # False - not muted
+  fi
+}
+
+# Run diagnostics (returns 0 if all good, 1 if issues)
+run_diagnostics() {
+  local issues=0
+
+  # Check session-start hook
+  if [[ ! -f "$SESSION_START_HOOK" ]]; then
+    echo -e "${RED}✗${NC} Session-start hook missing"
+    echo -e "${GRAY}  Expected: $SESSION_START_HOOK${NC}"
+    ((issues++))
+  elif [[ ! -x "$SESSION_START_HOOK" ]]; then
+    echo -e "${YELLOW}⚠${NC} Session-start hook not executable"
+    echo -e "${GRAY}  Run: chmod +x $SESSION_START_HOOK${NC}"
+    ((issues++))
+  fi
+
+  # Check play-tts script
+  if [[ ! -f "$PLAY_TTS_SCRIPT" ]]; then
+    echo -e "${RED}✗${NC} TTS playback script missing"
+    echo -e "${GRAY}  Expected: $PLAY_TTS_SCRIPT${NC}"
+    ((issues++))
+  fi
+
+  # Check if lite mode needs post-tool-use hook
+  local current_mode=$(get_current_mode)
+  if [[ "$current_mode" == "lite" ]] && [[ ! -f "$POST_TOOL_USE_HOOK" ]]; then
+    echo -e "${YELLOW}⚠${NC} Lite mode requires post-tool-use hook"
+    echo -e "${GRAY}  Run: /agent-vibes:mode lite to reinstall${NC}"
+    ((issues++))
+  fi
+
+  return $issues
+}
+
+# Main help display
+main() {
+  echo ""
+  echo "═══════════════════════════════════════════"
+  echo "  AgentVibes Help & Status"
+  echo "═══════════════════════════════════════════"
+  echo ""
+
+  # Run diagnostics silently and capture status
+  local diagnostic_output
+  diagnostic_output=$(run_diagnostics 2>&1)
+  local diagnostic_status=$?
+
+  # Show status indicator
+  if is_muted; then
+    echo -e "🔇 ${YELLOW}TTS is currently MUTED${NC}"
+    echo ""
+  elif [[ $diagnostic_status -eq 0 ]]; then
+    echo -e "🟢 ${GREEN}TTS is working normally!${NC}"
+    echo ""
+  else
+    echo -e "⚠️  ${YELLOW}TTS may not be working properly${NC}"
+    echo ""
+    echo "Issues Found:"
+    echo "$diagnostic_output"
+    echo ""
+  fi
+
+  # Show current settings
+  local current_mode=$(get_current_mode)
+  local current_voice=$(get_current_voice)
+  local current_provider=$(get_current_provider)
+  local current_verbosity=$(get_current_verbosity)
+
+  echo "Current Settings:"
+  if [[ "$current_mode" == "lite" ]]; then
+    echo -e "  ${BLUE}Mode:${NC} Lite Mode (minimal overhead)"
+  else
+    echo -e "  ${BLUE}Mode:${NC} Full Mode (all features)"
+  fi
+  echo -e "  ${BLUE}Voice:${NC} $current_voice"
+  echo -e "  ${BLUE}Provider:${NC} $current_provider"
+  echo -e "  ${BLUE}Verbosity:${NC} $current_verbosity"
+  echo ""
+
+  # Show available commands
+  echo "Available Commands:"
+  echo -e "  ${GREEN}/agent-vibes:mode lite${NC}     - Switch to minimal overhead mode"
+  echo -e "  ${GREEN}/agent-vibes:mode full${NC}     - Switch to full features mode"
+  echo -e "  ${GREEN}/agent-vibes:mute${NC}          - Temporarily silence TTS"
+  echo -e "  ${GREEN}/agent-vibes:unmute${NC}        - Re-enable TTS"
+  echo -e "  ${GREEN}/agent-vibes:voices:list${NC}   - See available voices"
+  echo ""
+
+  # Show suggested fixes if issues found
+  if [[ $diagnostic_status -ne 0 ]]; then
+    echo "Suggested Fixes:"
+    echo -e "  ${YELLOW}1.${NC} Try reinstalling: ${GREEN}npx agentvibes install${NC}"
+    echo -e "  ${YELLOW}2.${NC} Restore from backup: ${GREEN}/agent-vibes:mode restore${NC}"
+    echo -e "  ${YELLOW}3.${NC} Report issue: ${BLUE}https://github.com/paulpreibisch/AgentVibes/issues${NC}"
+    echo ""
+  fi
+
+  # Show help resources
+  echo "Need Help?"
+  echo -e "  ${BLUE}•${NC} Documentation: ${BLUE}https://agentvibes.org${NC}"
+  echo -e "  ${BLUE}•${NC} GitHub Issues: ${BLUE}https://github.com/paulpreibisch/AgentVibes/issues${NC}"
+  echo -e "  ${BLUE}•${NC} Lite Mode Guide: ${BLUE}.agentvibes/LITE-MODE.md${NC}"
+  echo ""
+  echo "═══════════════════════════════════════════"
+  echo ""
+}
+
+main "$@"