agentvibes 5.13.1 → 5.15.0

package/RELEASE_NOTES.md

@@ -1,5 +1,144 @@
 # AgentVibes Release Notes
 
+## v5.15.0 — Multi-session control on Windows
+
+**Released:** 2026-07-20 · `npm install agentvibes@latest`
+
+If you run several agent sessions at once, this release gives Windows the same
+control macOS and Linux gained in 5.13.0: sessions stay quiet unless you turn
+them on, and each one can tell you which window is speaking.
+
+### Sessions no longer all speak at once
+
+Running AgentVibes across several projects previously meant every open session
+announced itself, with no straightforward way to keep just one talking. On
+macOS and Linux this was addressed in 5.13.0. **On Windows it was not** — the
+Windows session hook enabled speech in every session regardless of your
+settings.
+
+Windows now follows the same rule: a session speaks only in a project you have
+explicitly enabled. Projects you have not enabled contribute **nothing at all**
+— not silent audio, but no added instructions and no token cost.
+
+### Mute now works on Windows
+
+`/agent-vibes:mute` had no effect on Windows audio. It silenced macOS and Linux
+only, because the Windows player read a different setting than the one the
+command wrote.
+
+Both the project mute and the global switch are now honoured on Windows:
+
+- `/agent-vibes:mute` — quiet this project
+- `/agent-vibes:unmute` — turn this project back on, even while everything else
+  is globally muted
+
+This makes "off everywhere, on in the one project I am working in" a single
+pair of commands on every platform.
+
+### Sessions can identify themselves on Windows
+
+Include `{{session}}` in your pretext and a session introduces itself once:
+
+```
+Claude on my-app in Windows Terminal
+```
+
+It names the project and detects the terminal — Windows Terminal, VS Code,
+Ghostty, iTerm, Terminal, WezTerm, tmux and others. Announced once per session
+rather than before every line. This previously worked only on macOS and Linux.
+
+### A related fix for every platform
+
+The script that produces that introduction was missing from the update process,
+so on a global install it was never delivered and the feature silently did
+nothing. It is now included on macOS, Linux and Windows alike.
+
+### Upgrading
+
+Your existing choices are preserved — if you have already muted, unmuted, or
+enabled a project, updating leaves that setting alone.
+
+**One change worth noting for Windows users on a global install:** because
+sessions are now off unless enabled, a global Windows install will be quiet
+after updating. Turn on the projects you want with `/agent-vibes:unmute`.
+Project installs are enabled automatically and are unaffected.
+
+### Quality
+
+New regression tests assert that the session gate, the mute rules, and the
+self-identification behave identically on both runtimes, so the platforms
+cannot drift apart again without the build failing.
+
+---
+
+## v5.14.0 — Reliable setup and complete audio previews
+
+**Released:** 2026-07-19 · `npm install agentvibes@latest`
+
+This release focuses on two things: getting AgentVibes installed correctly on every platform, and making the Preview button an accurate representation of how your agent will actually sound. It also includes everything from 5.13.2, which was tagged but never published to npm.
+
+### Setup now completes properly on macOS and Linux
+
+Installing Piper and downloading voices now runs correctly on a fresh macOS or Linux machine. Previously these steps could report a failure without having run, which left new users without a working voice engine and no clear way forward. This was a long-standing issue affecting first-time installs specifically — if you gave up on setup previously, it is worth another try.
+
+Related: several setup scripts are now stored in the correct line-ending format, so they execute properly on macOS and Linux.
+
+### Preview plays your complete audio mix
+
+The Preview button now plays exactly what your agent will sound like: your selected **voice**, any **reverb or audio effects**, and your **background music**, mixed together.
+
+Two cases previously played an incomplete mix. Hermes agent previews omitted background music entirely, and on Windows the music track was dropped whenever ffmpeg — the component that mixes music with speech — was unavailable. Both are resolved, and if ffmpeg is missing you now receive a clear message identifying it rather than silently reduced audio.
+
+### Your customisations survive updates
+
+If you have edited any of the hook scripts AgentVibes installs, updating now preserves your work. Your version is copied to a timestamped backup before any file is replaced:
+
+```
+play-tts.ps1.user.bak.20260719-143052
+```
+
+Each update creates its own backup, so earlier versions remain recoverable. On Windows, update coverage extended from 8 scripts to all 25.
+
+### Audio destination is clearer at a glance
+
+Settings now colour-codes where your audio plays: **Local** in green, **Remote** in red. This makes it immediately obvious when audio is being routed to another machine.
+
+### Voice previews use the correct engine
+
+Previewing a voice now uses that voice's own engine rather than the global setting, and identifies which engine you are hearing. Windows and macOS system voices work correctly through remote previews, and the Windows voice list now shows only voices that can actually be selected.
+
+### Windows remote audio
+
+Sending audio from a Windows machine to another computer no longer alters file paths in transit, which previously prevented background music from reaching the receiver.
+
+### Package and quality
+
+The published package no longer includes unnecessary files, and everything the application references is now present. The full test suite passes on Windows, macOS and Linux from a clean checkout, with new regression tests covering the preview behaviour described above.
+
+---
+
+## 🔧 v5.13.2 — Cleaner installs, smoother setup
+
+**Released:** 2026-07-17 · on `latest` — `npm install agentvibes@latest`
+
+### 🎛️ You start with the default settings, ready to make your own
+
+Fresh installs now begin clean, with the built-in defaults for voice, background music, and personality — so it's your setup from the very first run.
+
+### 🐧 Mac and Linux setup works properly
+
+A few of the scripts that set things up were saved in a Windows format that Mac and Linux can't read, so they'd stop before doing anything. They're in the right format now. Installing Piper and downloading voices work on a fresh Mac or Linux machine again.
+
+### 🔊 Your voice choice sticks
+
+The settings file that remembers which voice goes with which engine could be read slightly wrong, so your engine choice quietly got ignored. Fixed — what you pick is what you get.
+
+### 📦 A smaller, tidier download
+
+The package no longer carries files it never needed. Everything the app tells you to run is now actually included.
+
+---
+
 ## 🔧 v5.13.1 — Windows updates that actually update
 
 **Released:** 2026-07-16 · on `latest` — `npm install agentvibes@latest`

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);
+}