agentvibes 5.12.0-alpha.0 → 5.12.0

package/RELEASE_NOTES.md

@@ -1,5 +1,43 @@
 # AgentVibes Release Notes
 
+## 🎉 v5.12.0 — The Fable Week Overhaul (Stable)
+
+**Released:** 2026-07-05 · now on `latest` — `npm install agentvibes`
+
+This turns the "Fable Week" alpha into a stable release. During a week of early access to Anthropic's new **Fable** model, we pointed it at the whole AgentVibes codebase and rebuilt the core properly.
+
+### A stronger, shared core
+
+Every time AgentVibes speaks it makes a lot of decisions — which voice, which engine, whether to play here or send the audio to another machine, background music, volume, mute. That logic had been copied into several separate scripts (Mac/Linux, Windows, remote, and the voice server), and the copies slowly **drifted apart** — a fix in one was missed in the others, which is why certain glitches kept coming back.
+
+We replaced all of it with **one shared core** that every part of AgentVibes now follows — one place to fix, one place to trust. What you'll notice:
+
+- **Kokoro voices that were silent on Linux now work everywhere.**
+- **Your voice choices stick** — settings no longer get quietly overridden.
+- **Volume, mute, and remote playback behave the same** across Mac, Linux, and Windows.
+- **Safe by default** — if the new core isn't available on your machine, AgentVibes falls back to the old behaviour, so it never just stops talking.
+
+### Previews now play in the right place
+
+Previewing a voice or track used to play on whatever machine you were sitting at — which was silent if you'd set AgentVibes up to send its audio elsewhere. Now:
+
+- **If you have SSH remote configured, previews play on your receiver; otherwise they play locally, like before.**
+- This covers **voice previews** (Piper and Kokoro) from the Setup, Agent, and Settings screens, and **music/track previews** — press Space to play, Space again to stop.
+
+### A simpler voice menu
+
+- We **removed the redundant Voices tab.** It only ever listed Piper voices and confused people, since choosing a voice for any provider already lives in **Setup**.
+
+### Groundwork for what's next
+
+- The receiver now also receives the **full path of the project folder** a message came from (a new `projectPath` field, alongside the project name it already got) — laying the groundwork for upcoming enhancements.
+
+### Reviewed before shipping
+
+We ran three independent reviews over the changes — security, correctness, and regressions — and fixed every real issue before release.
+
+---
+
 ## 🧪 v5.12.0-alpha.0 — The "Fable Week" Overhaul (ALPHA / testing)
 
 **Published:** 2026-07-04 · dist-tag **`alpha`** (not `latest`). Try it with `npm install agentvibes@alpha`.

package/WINDOWS-SETUP.md

@@ -1,208 +1,208 @@
-# AgentVibes Windows Native Setup
-
-This folder contains AgentVibes configured for **native Windows** (not WSL) with three TTS providers available.
-
-## Quick Start
-
-### 1. Open in VS Code (Native Windows)
-
-- **File > Open Folder** > Select this folder (`agentvibes-in-windows`)
-- Make sure you're opening in **native Windows VS Code** (not WSL remote)
-
-### 2. Open PowerShell Terminal
-
-- **Terminal > New Terminal**
-- Change shell to **PowerShell** (if needed)
-
-### 3. Run Setup
-
-```powershell
-.\setup-windows.ps1
-```
-
-This script will:
-- Check PowerShell version (5.1+)
-- Create `.claude` directories
-- Let you choose TTS provider (Piper or SAPI)
-- Install Piper if you choose it
-- Download a default voice model
-- Test TTS
-- Configure for first use
-
-### 4. Install Dependencies
-
-```powershell
-npm install
-```
-
-### 5. Start Using AgentVibes
-
-Open a Claude Code session in this project. The SessionStart hook will automatically inject TTS protocol instructions, causing Claude to speak all responses.
-
-## TTS Providers
-
-### Option 1: Soprano (Best Quality)
-- **Quality**: Ultra-high (80M parameter neural model)
-- **Voices**: Single high-quality voice (Soprano-1.1-80M)
-- **Download**: `pip install soprano-tts`
-- **Setup**: Start WebUI with `soprano-webui` or API with `uvicorn soprano.server:app`
-- **Speed**: GPU-accelerated, very fast
-- **Features**: Gradio WebUI mode, OpenAI-compatible API mode, CLI fallback
-
-To set up Soprano:
-```powershell
-# Install Soprano
-pip install soprano-tts
-
-# Start WebUI (recommended - stays running in background)
-soprano-webui
-
-# Set provider
-.\.claude\hooks-windows\provider-manager.ps1 set soprano
-
-# Test
-.\.claude\hooks-windows\play-tts-soprano.ps1 "Hello from Soprano"
-```
-
-### Option 2: Windows Piper (Recommended for Offline)
-- **Quality**: High (neural voices)
-- **Voices**: 50+ available
-- **Download**: ~100MB
-- **Setup**: Automatic (run `setup-windows.ps1`)
-- **Speed**: Offline synthesis
-- **Features**: All AgentVibes features supported
-
-### Option 3: Windows SAPI (Built-in, Zero Setup)
-- **Quality**: Basic
-- **Voices**: ~10 built-in (David, Zira, Mark)
-- **Download**: 0 MB (no installation needed)
-- **Setup**: Select during `setup-windows.ps1`
-- **Speed**: Fast
-- **Features**: Core TTS only
-
-## Claude Code Integration
-
-AgentVibes hooks into Claude Code via `.claude/settings.json`. The SessionStart hook runs automatically when Claude starts a session:
-
-```json
-{
-  "hooks": {
-    "SessionStart": [{
-      "hooks": [{
-        "type": "command",
-        "command": "powershell -NoProfile -ExecutionPolicy Bypass -File \"$CLAUDE_PROJECT_DIR\\.claude\\hooks-windows\\session-start-tts.ps1\""
-      }]
-    }]
-  }
-}
-```
-
-This injects TTS protocol instructions so Claude speaks every response using the configured provider.
-
-## Manual Commands
-
-Test TTS manually:
-
-```powershell
-# Test current provider
-.\.claude\hooks-windows\play-tts.ps1 "Hello from Windows"
-
-# Test specific providers
-.\.claude\hooks-windows\play-tts-windows-sapi.ps1 "Hello SAPI"
-.\.claude\hooks-windows\play-tts-windows-piper.ps1 "Hello Piper"
-.\.claude\hooks-windows\play-tts-soprano.ps1 "Hello Soprano"
-
-# List available voices
-.\.claude\hooks-windows\voice-manager-windows.ps1 list
-
-# Switch voice (for Piper/SAPI)
-.\.claude\hooks-windows\voice-manager-windows.ps1 switch "en_US-lessac-high"
-
-# List providers
-.\.claude\hooks-windows\provider-manager.ps1 list
-
-# Switch provider
-.\.claude\hooks-windows\provider-manager.ps1 set soprano
-.\.claude\hooks-windows\provider-manager.ps1 set windows-piper
-.\.claude\hooks-windows\provider-manager.ps1 set windows-sapi
-```
-
-## Troubleshooting
-
-### PowerShell Execution Policy Error
-
-If you get an "execution policy" error, run:
-
-```powershell
-Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
-```
-
-Then try again.
-
-### No Audio Playing
-
-1. Check Windows volume isn't muted
-2. Try switching to SAPI provider (zero-setup): `.\.claude\hooks-windows\provider-manager.ps1 set windows-sapi`
-3. Test SAPI directly: `.\.claude\hooks-windows\play-tts-windows-sapi.ps1 "test"`
-
-### Soprano Not Detected
-
-1. Ensure soprano-webui is running: `soprano-webui`
-2. Check port 7860 is accessible: `Test-NetConnection -ComputerName 127.0.0.1 -Port 7860`
-3. Set custom port if needed: `$env:SOPRANO_PORT = "8080"` before running TTS
-
-### Piper Installation Failed
-
-1. Check internet connection
-2. Run setup again: `.\setup-windows.ps1`
-3. Or manually download from: https://github.com/rhasspy/piper/releases
-
-### Can't Find Voice
-
-For Piper, voices are stored in: `%USERPROFILE%\.claude\piper-voices\`
-
-You can download additional voices with `.\download-piper-voices.ps1`.
-
-## Architecture
-
-```
-agentvibes-in-windows/
-├── .claude/
-│   ├── hooks-windows/               # PowerShell TTS scripts
-│   │   ├── play-tts.ps1             # Main router (dispatches to active provider)
-│   │   ├── play-tts-soprano.ps1     # Soprano provider
-│   │   ├── play-tts-windows-piper.ps1  # Piper provider
-│   │   ├── play-tts-windows-sapi.ps1   # SAPI provider
-│   │   ├── soprano-gradio-synth.py  # Python helper for Soprano Gradio API
-│   │   ├── provider-manager.ps1     # Provider switching
-│   │   ├── voice-manager-windows.ps1   # Voice management
-│   │   ├── session-start-tts.ps1    # SessionStart hook (injects TTS protocol)
-│   │   └── audio-cache-utils.ps1    # Audio cache cleanup
-│   ├── settings.json                # Claude Code hooks config
-│   ├── audio/                       # Audio cache (auto-created)
-│   ├── piper-voices/                # Piper voice models (auto-created)
-│   └── tts-provider.txt             # Active provider config
-├── setup-windows.ps1                # Installation script
-├── download-piper-voices.ps1        # Download additional Piper voices
-└── WINDOWS-SETUP.md                 # This file
-```
-
-## What's Different from WSL
-
-| Feature | WSL Version | Windows Native |
-|---------|-------------|----------------|
-| **TTS Scripts** | Bash shell scripts (.sh) | PowerShell scripts (.ps1) |
-| **Audio** | PulseAudio/paplay | System.Media.SoundPlayer |
-| **Providers** | Piper, macOS, Termux, Soprano | Piper, SAPI, Soprano |
-| **Setup** | WSL + PulseAudio config | Native Windows only |
-| **Hook Dir** | `.claude/hooks/` | `.claude/hooks-windows/` |
-
-## Support
-
-- **Documentation**: https://agentvibes.org
-- **Issues**: https://github.com/paulpreibisch/AgentVibes/issues
-
----
-
-**Version**: 2.0 (Windows Native + Soprano)
-**Last Updated**: 2026-02-11
+# AgentVibes Windows Native Setup
+
+This folder contains AgentVibes configured for **native Windows** (not WSL) with three TTS providers available.
+
+## Quick Start
+
+### 1. Open in VS Code (Native Windows)
+
+- **File > Open Folder** > Select this folder (`agentvibes-in-windows`)
+- Make sure you're opening in **native Windows VS Code** (not WSL remote)
+
+### 2. Open PowerShell Terminal
+
+- **Terminal > New Terminal**
+- Change shell to **PowerShell** (if needed)
+
+### 3. Run Setup
+
+```powershell
+.\setup-windows.ps1
+```
+
+This script will:
+- Check PowerShell version (5.1+)
+- Create `.claude` directories
+- Let you choose TTS provider (Piper or SAPI)
+- Install Piper if you choose it
+- Download a default voice model
+- Test TTS
+- Configure for first use
+
+### 4. Install Dependencies
+
+```powershell
+npm install
+```
+
+### 5. Start Using AgentVibes
+
+Open a Claude Code session in this project. The SessionStart hook will automatically inject TTS protocol instructions, causing Claude to speak all responses.
+
+## TTS Providers
+
+### Option 1: Soprano (Best Quality)
+- **Quality**: Ultra-high (80M parameter neural model)
+- **Voices**: Single high-quality voice (Soprano-1.1-80M)
+- **Download**: `pip install soprano-tts`
+- **Setup**: Start WebUI with `soprano-webui` or API with `uvicorn soprano.server:app`
+- **Speed**: GPU-accelerated, very fast
+- **Features**: Gradio WebUI mode, OpenAI-compatible API mode, CLI fallback
+
+To set up Soprano:
+```powershell
+# Install Soprano
+pip install soprano-tts
+
+# Start WebUI (recommended - stays running in background)
+soprano-webui
+
+# Set provider
+.\.claude\hooks-windows\provider-manager.ps1 set soprano
+
+# Test
+.\.claude\hooks-windows\play-tts-soprano.ps1 "Hello from Soprano"
+```
+
+### Option 2: Windows Piper (Recommended for Offline)
+- **Quality**: High (neural voices)
+- **Voices**: 50+ available
+- **Download**: ~100MB
+- **Setup**: Automatic (run `setup-windows.ps1`)
+- **Speed**: Offline synthesis
+- **Features**: All AgentVibes features supported
+
+### Option 3: Windows SAPI (Built-in, Zero Setup)
+- **Quality**: Basic
+- **Voices**: ~10 built-in (David, Zira, Mark)
+- **Download**: 0 MB (no installation needed)
+- **Setup**: Select during `setup-windows.ps1`
+- **Speed**: Fast
+- **Features**: Core TTS only
+
+## Claude Code Integration
+
+AgentVibes hooks into Claude Code via `.claude/settings.json`. The SessionStart hook runs automatically when Claude starts a session:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [{
+      "hooks": [{
+        "type": "command",
+        "command": "powershell -NoProfile -ExecutionPolicy Bypass -File \"$CLAUDE_PROJECT_DIR\\.claude\\hooks-windows\\session-start-tts.ps1\""
+      }]
+    }]
+  }
+}
+```
+
+This injects TTS protocol instructions so Claude speaks every response using the configured provider.
+
+## Manual Commands
+
+Test TTS manually:
+
+```powershell
+# Test current provider
+.\.claude\hooks-windows\play-tts.ps1 "Hello from Windows"
+
+# Test specific providers
+.\.claude\hooks-windows\play-tts-windows-sapi.ps1 "Hello SAPI"
+.\.claude\hooks-windows\play-tts-windows-piper.ps1 "Hello Piper"
+.\.claude\hooks-windows\play-tts-soprano.ps1 "Hello Soprano"
+
+# List available voices
+.\.claude\hooks-windows\voice-manager-windows.ps1 list
+
+# Switch voice (for Piper/SAPI)
+.\.claude\hooks-windows\voice-manager-windows.ps1 switch "en_US-lessac-high"
+
+# List providers
+.\.claude\hooks-windows\provider-manager.ps1 list
+
+# Switch provider
+.\.claude\hooks-windows\provider-manager.ps1 set soprano
+.\.claude\hooks-windows\provider-manager.ps1 set windows-piper
+.\.claude\hooks-windows\provider-manager.ps1 set windows-sapi
+```
+
+## Troubleshooting
+
+### PowerShell Execution Policy Error
+
+If you get an "execution policy" error, run:
+
+```powershell
+Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
+```
+
+Then try again.
+
+### No Audio Playing
+
+1. Check Windows volume isn't muted
+2. Try switching to SAPI provider (zero-setup): `.\.claude\hooks-windows\provider-manager.ps1 set windows-sapi`
+3. Test SAPI directly: `.\.claude\hooks-windows\play-tts-windows-sapi.ps1 "test"`
+
+### Soprano Not Detected
+
+1. Ensure soprano-webui is running: `soprano-webui`
+2. Check port 7860 is accessible: `Test-NetConnection -ComputerName 127.0.0.1 -Port 7860`
+3. Set custom port if needed: `$env:SOPRANO_PORT = "8080"` before running TTS
+
+### Piper Installation Failed
+
+1. Check internet connection
+2. Run setup again: `.\setup-windows.ps1`
+3. Or manually download from: https://github.com/rhasspy/piper/releases
+
+### Can't Find Voice
+
+For Piper, voices are stored in: `%USERPROFILE%\.claude\piper-voices\`
+
+You can download additional voices with `.\download-piper-voices.ps1`.
+
+## Architecture
+
+```
+agentvibes-in-windows/
+├── .claude/
+│   ├── hooks-windows/               # PowerShell TTS scripts
+│   │   ├── play-tts.ps1             # Main router (dispatches to active provider)
+│   │   ├── play-tts-soprano.ps1     # Soprano provider
+│   │   ├── play-tts-windows-piper.ps1  # Piper provider
+│   │   ├── play-tts-windows-sapi.ps1   # SAPI provider
+│   │   ├── soprano-gradio-synth.py  # Python helper for Soprano Gradio API
+│   │   ├── provider-manager.ps1     # Provider switching
+│   │   ├── voice-manager-windows.ps1   # Voice management
+│   │   ├── session-start-tts.ps1    # SessionStart hook (injects TTS protocol)
+│   │   └── audio-cache-utils.ps1    # Audio cache cleanup
+│   ├── settings.json                # Claude Code hooks config
+│   ├── audio/                       # Audio cache (auto-created)
+│   ├── piper-voices/                # Piper voice models (auto-created)
+│   └── tts-provider.txt             # Active provider config
+├── setup-windows.ps1                # Installation script
+├── download-piper-voices.ps1        # Download additional Piper voices
+└── WINDOWS-SETUP.md                 # This file
+```
+
+## What's Different from WSL
+
+| Feature | WSL Version | Windows Native |
+|---------|-------------|----------------|
+| **TTS Scripts** | Bash shell scripts (.sh) | PowerShell scripts (.ps1) |
+| **Audio** | PulseAudio/paplay | System.Media.SoundPlayer |
+| **Providers** | Piper, macOS, Termux, Soprano | Piper, SAPI, Soprano |
+| **Setup** | WSL + PulseAudio config | Native Windows only |
+| **Hook Dir** | `.claude/hooks/` | `.claude/hooks-windows/` |
+
+## Support
+
+- **Documentation**: https://agentvibes.org
+- **Issues**: https://github.com/paulpreibisch/AgentVibes/issues
+
+---
+
+**Version**: 2.0 (Windows Native + Soprano)
+**Last Updated**: 2026-02-11

package/bin/agent-vibes

@@ -1,40 +1,40 @@
 #!/usr/bin/env node
-
-/**
- * AgentVibes - Beautiful ElevenLabs TTS voice commands for Claude Code
- * This file ensures proper execution when run via npx
- */
-
-import { execFileSync } from 'node:child_process';
-import path from 'node:path';
-import fs from 'node:fs';
-import { fileURLToPath } from 'node:url';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-
-// Check if we're running in an npx temporary directory
-const isNpxExecution = __dirname.includes('_npx') || __dirname.includes('.npm');
-
-// Get CLI arguments
-const arguments_ = process.argv.slice(2);
-
-// Route through the TUI console (agentvibes.js) which handles install/config/etc
-const installerPath = path.join(__dirname, 'agentvibes.js');
-
-if (!fs.existsSync(installerPath)) {
-  console.error('Error: Could not find installer.js at', installerPath);
-  console.error('Current directory:', __dirname);
-  process.exit(1);
-}
-
-try {
-  // Security: Use execFileSync with array args to prevent command injection
-  // Arguments are passed as array elements, not string interpolation
-  execFileSync('node', [installerPath, ...arguments_], {
-    stdio: 'inherit',
-    cwd: path.dirname(__dirname),
-  });
-} catch (error) {
-  process.exit(error.status || 1);
-}
+
+/**
+ * AgentVibes - Beautiful ElevenLabs TTS voice commands for Claude Code
+ * This file ensures proper execution when run via npx
+ */
+
+import { execFileSync } from 'node:child_process';
+import path from 'node:path';
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Check if we're running in an npx temporary directory
+const isNpxExecution = __dirname.includes('_npx') || __dirname.includes('.npm');
+
+// Get CLI arguments
+const arguments_ = process.argv.slice(2);
+
+// Route through the TUI console (agentvibes.js) which handles install/config/etc
+const installerPath = path.join(__dirname, 'agentvibes.js');
+
+if (!fs.existsSync(installerPath)) {
+  console.error('Error: Could not find installer.js at', installerPath);
+  console.error('Current directory:', __dirname);
+  process.exit(1);
+}
+
+try {
+  // Security: Use execFileSync with array args to prevent command injection
+  // Arguments are passed as array elements, not string interpolation
+  execFileSync('node', [installerPath, ...arguments_], {
+    stdio: 'inherit',
+    cwd: path.dirname(__dirname),
+  });
+} catch (error) {
+  process.exit(error.status || 1);
+}