agentvibes 5.6.0 → 5.6.2

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

@@ -1,4 +1,4 @@
-#
+#
 # File: .claude/hooks-windows/play-tts.ps1
 #
 # AgentVibes - Windows TTS Router
@@ -19,6 +19,18 @@ param(
     [string]$llm = ""
 )
 
+# Text-file handoff: the SSH receiver watcher writes long/special-char text to
+# a UTF-8 temp file and passes the sentinel "__from_file__" on the command line
+# to avoid Windows CLI argument mangling. Load the real text here.
+if ($Text -eq "__from_file__" -and $env:AGENTVIBES_TEXT_FILE) {
+    if (Test-Path $env:AGENTVIBES_TEXT_FILE) {
+        $Text = [System.IO.File]::ReadAllText($env:AGENTVIBES_TEXT_FILE, [System.Text.UTF8Encoding]::new($false))
+    } else {
+        Write-Error "AGENTVIBES_TEXT_FILE set to missing path: $($env:AGENTVIBES_TEXT_FILE)"
+        exit 1
+    }
+}
+
 # Configuration paths
 # First check if we're running from a project directory with .claude
 $ScriptPath = Split-Path -Parent $MyInvocation.MyCommand.Path
@@ -53,11 +65,13 @@ if (Test-Path $ProviderFile) {
 $ProviderScript = ""
 
 switch ($ActiveProvider) {
-    "windows-sapi" {
-        $ProviderScript = "$HooksDir\play-tts-windows-sapi.ps1"
+    { $_ -in "sapi", "windows-sapi" } {
+        $ProviderScript = "$HooksDir\play-tts-sapi.ps1"
+        if (-not (Test-Path $ProviderScript)) { $ProviderScript = "$HooksDir\play-tts-windows-sapi.ps1" }
     }
-    "windows-piper" {
-        $ProviderScript = "$HooksDir\play-tts-windows-piper.ps1"
+    { $_ -in "piper", "windows-piper" } {
+        $ProviderScript = "$HooksDir\play-tts-piper.ps1"
+        if (-not (Test-Path $ProviderScript)) { $ProviderScript = "$HooksDir\play-tts-windows-piper.ps1" }
     }
     "soprano" {
         $ProviderScript = "$HooksDir\play-tts-soprano.ps1"
@@ -83,6 +97,16 @@ if (Test-Path $BgEnabledFile) {
     $BgEnabled = (Get-Content $BgEnabledFile -Raw).Trim() -eq "true"
 }
 
+# Per-message overrides from SSH/remote payload (set by the queue watcher).
+# These allow remote senders (Hermes, SSH remote provider) to override music,
+# volume, and effects for a single message without mutating persistent config.
+$OverrideMusic   = if ($env:AGENTVIBES_OVERRIDE_MUSIC)   { $env:AGENTVIBES_OVERRIDE_MUSIC.Trim() }   else { "" }
+$OverrideVolume  = if ($env:AGENTVIBES_OVERRIDE_VOLUME)  { $env:AGENTVIBES_OVERRIDE_VOLUME.Trim() }  else { "" }
+$OverrideEffects = if ($env:AGENTVIBES_OVERRIDE_EFFECTS) { $env:AGENTVIBES_OVERRIDE_EFFECTS.Trim() } else { "" }
+
+# If a music override is set, force background music on for this message
+if ($OverrideMusic -ne "") { $BgEnabled = $true }
+
 # Check if reverb is enabled (allowlist validation)
 $ReverbLevel = "off"
 $ReverbFile = "$ConfigDir\reverb-level.txt"
@@ -92,6 +116,12 @@ if (Test-Path $ReverbFile) {
         $ReverbLevel = $reverbVal
     }
 }
+# Per-message reverb override: AGENTVIBES_OVERRIDE_EFFECTS accepts a preset name
+# ("off", "light", "medium", "heavy", "cathedral") — Sox effect strings are Linux-only
+# and are silently ignored on Windows.
+if ($OverrideEffects -ne "" -and $OverrideEffects -in @("off", "light", "medium", "heavy", "cathedral")) {
+    $ReverbLevel = $OverrideEffects
+}
 $HasReverb = $ReverbLevel -ne "off"
 
 # Check ffmpeg availability for background music mixing or reverb
@@ -282,12 +312,14 @@ if ($env:AGENTVIBES_VERBOSE -eq "1") {
 # ffplay uses libswresample with sinc resampling — no artefacts.
 function Invoke-AudioPlay {
     param([string]$FilePath)
-    $fp = (Get-Command ffplay -ErrorAction SilentlyContinue)?.Source
+    $ffplayCmd = Get-Command ffplay -ErrorAction SilentlyContinue
+    $fp = if ($ffplayCmd) { $ffplayCmd.Source } else { $null }
     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
+        $ffplayCmd = Get-Command ffplay -ErrorAction SilentlyContinue
+        $fp = if ($ffplayCmd) { $ffplayCmd.Source } else { $null }
     }
     if ($fp) {
         & $fp -autoexit -nodisp -loglevel quiet $FilePath 2>$null
@@ -364,6 +396,21 @@ if (($BgEnabled -or $HasReverb) -and $HasFfmpeg) {
                     $DefaultTrack = $configTrack
                 }
             }
+            # Per-message music override from remote payload (e.g. Hermes, SSH remote)
+            # Accepts full filename (e.g. "agent_vibes_bachata_v1_loop.mp3") or a
+            # keyword (e.g. "bachata") — keyword triggers a glob search in TracksDir.
+            if ($OverrideMusic -ne "") {
+                if ($OverrideMusic -match '^[a-zA-Z0-9_\-\.]+$') {
+                    if ($OverrideMusic -match '\.mp3$') {
+                        # Full filename — use directly
+                        $DefaultTrack = $OverrideMusic
+                    } else {
+                        # Keyword — find first matching track file
+                        $matched = Get-ChildItem -Path $TracksDir -Filter "*$OverrideMusic*" -File -ErrorAction SilentlyContinue | Select-Object -First 1
+                        if ($matched) { $DefaultTrack = $matched.Name }
+                    }
+                }
+            }
             $BgTrackPath = Join-Path $TracksDir $DefaultTrack
             # Path containment: verify resolved path stays within tracks directory
             $ResolvedBgTrack = [System.IO.Path]::GetFullPath($BgTrackPath)
@@ -372,13 +419,16 @@ if (($BgEnabled -or $HasReverb) -and $HasFfmpeg) {
                 $BgTrackPath = Join-Path $TracksDir "agent_vibes_bachata_v1_loop.mp3"
             }
 
-            # Get volume (default 0.25)
+            # Get volume (default 0.25) — per-message override takes precedence
             $BgVolume = "0.25"
             $VolumeFile = "$ConfigDir\background-music-volume.txt"
             if (Test-Path $VolumeFile) {
                 $vol = (Get-Content $VolumeFile -Raw).Trim()
                 if ($vol -match '^\d+\.?\d*$') { $BgVolume = $vol }
             }
+            if ($OverrideVolume -ne "" -and $OverrideVolume -match '^\d+\.?\d*$') {
+                $BgVolume = $OverrideVolume
+            }
 
             if (Test-Path $BgTrackPath) {
                 $MixedFile = $RecentWav.FullName -replace '\.wav$', '-mixed.wav'

package/.claude/piper-voices-dir.txt

@@ -1 +1 @@
-/home/fire/.claude/piper-voices
+/home/administrator/.claude/piper-voices

package/.clawdbot/skill/README.md

@@ -0,0 +1,326 @@
+# 🎤 AgentVibes OpenClaw Skill
+
+> **Give your voiceless server a voice!** Professional text-to-speech for OpenClaw AI agents running on remote servers, VPS, Mac Minis, or isolated hardware.
+
+[![npm version](https://img.shields.io/npm/v/agentvibes)](https://www.npmjs.com/package/agentvibes)
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+
+**Published by**: Paul Preibisch ([@997Fire](https://x.com/997Fire))
+**ClawHub**: https://clawhub.ai/paulpreibisch/agentvibes-openclaw-skill
+**Full Documentation**: https://github.com/paulpreibisch/AgentVibes#-openclaw-integration
+
+---
+
+## 🎯 What This Skill Does
+
+AgentVibes adds **professional voice output** to your OpenClaw AI agent using intelligent text streaming—no matter where your agent is running (Mac Mini, VPS, old PC, cloud server).
+
+### The Problem
+
+You've wisely deployed OpenClaw on isolated hardware for security. But now:
+- Your server has no speakers
+- Your AI agent is mute
+- You're stuck reading text responses
+- Mobile development is clunky
+
+### The Solution
+
+**Text streaming architecture**: Server sends text → Your device generates voice locally
+
+**Benefits:**
+- ✅ 99.9% less bandwidth than audio streaming (200KB vs 800MB per 100 responses)
+- ✅ Works on Linux, macOS, Android
+- ✅ 50+ voices in 30+ languages (free, offline)
+- ✅ Maintains security isolation
+- ✅ Walk, commute, or multitask while your agent talks
+
+---
+
+## 🚀 Quick Start
+
+### 1. Install AgentVibes on Your OpenClaw Server
+
+```bash
+# On your remote server where OpenClaw runs
+npx agentvibes install
+```
+
+This installs:
+- Piper TTS engine (free, offline)
+- 50+ professional AI voices
+- Voice management slash commands
+- Text streaming receiver support
+
+### 2. Test Voice Output
+
+```bash
+# Test that TTS works
+/agent-vibes:sample
+```
+
+You should hear audio through your device speakers!
+
+### 3. Customize Your Voice (Optional)
+
+```bash
+# List available voices
+/agent-vibes:list
+
+# Preview voices before choosing
+/agent-vibes:preview 5
+
+# Switch to your preferred voice
+/agent-vibes:switch en_US-amy-medium
+```
+
+---
+
+## 📱 Mobile Setup (Walk & Talk)
+
+Want your OpenClaw agent to speak to you while walking? Set up the **AgentVibes Receiver**:
+
+### For Android (Termux)
+
+```bash
+# On your Android phone
+pkg install termux-api openssh python
+pip install agentvibes
+
+# On your server, configure SSH host
+echo "android" > ~/.claude/ssh-remote-host.txt
+```
+
+Now text streams to your phone, generates voice locally, and plays through headphones—no button presses needed!
+
+**Full mobile setup**: https://github.com/paulpreibisch/AgentVibes#-openclaw-integration
+
+---
+
+## 🎭 Available Voices
+
+### English Voices
+- `en_US-lessac-medium` - Default male (clear, professional)
+- `en_US-amy-medium` - Friendly female
+- `en_US-ryan-high` - High quality male
+- `en_GB-alan-medium` - British male
+
+### Romance Languages
+- `es_ES-davefx-medium` - Spanish (Spain)
+- `fr_FR-siwis-medium` - French female
+- `it_IT-riccardo-x_low` - Italian male
+- `pt_BR-faber-medium` - Portuguese (Brazilian)
+
+### Asian Languages
+- `ja_JP-ayanami-medium` - Japanese female
+- `zh_CN-huayan-x_low` - Chinese female
+- `ko_KR-kss-medium` - Korean female
+
+**And 40+ more voices in 30+ languages!**
+
+---
+
+## 🎮 Voice Control Commands
+
+All commands available in OpenClaw chat:
+
+### Voice Selection
+```bash
+/agent-vibes:list              # Show all voices
+/agent-vibes:preview 5         # Preview first 5 voices
+/agent-vibes:switch <voice>    # Change voice
+/agent-vibes:get               # Show current voice
+```
+
+### Playback Control
+```bash
+/agent-vibes:mute              # Silence TTS
+/agent-vibes:unmute            # Restore voice
+/agent-vibes:replay            # Replay last audio
+/agent-vibes:replay 2          # Replay 2nd-to-last
+```
+
+### Advanced
+```bash
+/agent-vibes:provider list     # Show TTS providers
+/agent-vibes:set-speed 1.2     # Adjust speech rate
+/agent-vibes:personality       # Set voice personality
+/agent-vibes:verbosity high    # Control how much AI speaks
+```
+
+---
+
+## 🔧 Common Use Cases
+
+### 1. Code Reviews on the Go
+Walk to a meeting while your AI agent reviews PRs and explains issues verbally.
+
+### 2. Hands-Free Development
+Cook dinner while monitoring deployment status or test results via voice.
+
+### 3. Commute Learning
+Study new frameworks during your commute—have your agent explain concepts aloud.
+
+### 4. Multi-Language Development
+Switch to Spanish, French, or Japanese voices to hear code comments in native languages.
+
+### 5. Accessibility
+Fully accessible voice interface for developers who benefit from audio feedback.
+
+---
+
+## 🔒 Security Considerations
+
+**⚠️ CRITICAL**: If running OpenClaw on a remote server, read the security guide:
+
+https://github.com/paulpreibisch/AgentVibes/blob/master/docs/security-hardening-guide.md
+
+**Required security measures:**
+- SSH key-only authentication
+- Non-standard SSH port (e.g., 2222)
+- Firewall configuration (UFW/iptables)
+- Fail2ban for intrusion prevention
+- VPN tunneling (Tailscale recommended)
+
+**Never expose OpenClaw directly to the internet without hardening.**
+
+---
+
+## 🌍 Deployment Options
+
+AgentVibes works on all isolated OpenClaw deployments:
+
+### Mac Mini
+```bash
+# On your Mac Mini
+npx agentvibes install
+```
+
+### VPS (AWS, DigitalOcean, Database Mart, etc.)
+```bash
+# On your cloud server
+npx agentvibes install
+```
+
+### Old PC/Laptop (Repurposed Hardware)
+```bash
+# On your dedicated machine
+npx agentvibes install
+```
+
+### Docker Container
+```bash
+# Inside your OpenClaw container
+npx agentvibes install
+```
+
+---
+
+## 📊 Bandwidth Comparison
+
+**Traditional audio streaming:**
+- 8MB per response
+- 800MB per 100 responses
+- Expensive over cellular
+
+**AgentVibes text streaming:**
+- 2KB per response
+- 200KB per 100 responses
+- Negligible cellular cost
+
+**Savings: 99.975% bandwidth reduction**
+
+---
+
+## 🆘 Troubleshooting
+
+### No Audio Output
+
+```bash
+# Check if Piper is installed
+which piper
+
+# Test audio directly
+echo "Hello world" | piper --model en_US-lessac-medium --output_file test.wav
+aplay test.wav  # Linux
+afplay test.wav # macOS
+```
+
+### Voice Not Found
+
+```bash
+# List installed voices
+/agent-vibes:list
+
+# Download voice if missing
+npx agentvibes install
+```
+
+### SSH Audio Issues
+
+```bash
+# Verify SSH connection
+ssh your-server "echo Connected"
+
+# Check receiver script
+ls ~/.termux/agentvibes-play.sh  # Android
+ls ~/.agentvibes/play-remote.sh  # Linux/macOS
+```
+
+**Full troubleshooting guide**: https://github.com/paulpreibisch/AgentVibes/blob/master/docs/troubleshooting.md
+
+---
+
+## 📚 Additional Documentation
+
+### Full Guides
+- **Main README**: https://github.com/paulpreibisch/AgentVibes
+- **OpenClaw Integration**: https://github.com/paulpreibisch/AgentVibes#-openclaw-integration
+- **Security Hardening**: https://github.com/paulpreibisch/AgentVibes/blob/master/docs/security-hardening-guide.md
+- **Voice Library**: https://github.com/paulpreibisch/AgentVibes/blob/master/docs/voice-library.md
+- **Troubleshooting**: https://github.com/paulpreibisch/AgentVibes/blob/master/docs/troubleshooting.md
+
+### Community
+- **GitHub Issues**: https://github.com/paulpreibisch/AgentVibes/issues
+- **GitHub Discussions**: https://github.com/paulpreibisch/AgentVibes/discussions
+- **Website**: https://agentvibes.org
+
+---
+
+## 🤝 Contributing
+
+AgentVibes is open source (Apache 2.0)! Contributions welcome:
+
+- 🐛 Report bugs
+- 💡 Suggest features
+- 🌍 Add voice translations
+- 📝 Improve documentation
+- 🔧 Submit pull requests
+
+**Repository**: https://github.com/paulpreibisch/AgentVibes
+
+---
+
+## 📄 License
+
+Apache License 2.0 - see [LICENSE](https://github.com/paulpreibisch/AgentVibes/blob/master/LICENSE)
+
+---
+
+## 🙏 Credits
+
+**Created by**: Paul Preibisch
+**Twitter/X**: [@997Fire](https://x.com/997Fire)
+**Website**: https://agentvibes.org
+
+**Powered by**:
+- [Piper TTS](https://github.com/rhasspy/piper) - Fast, offline neural TTS
+- [Hugging Face Voice Models](https://huggingface.co/rhasspy/piper-voices) - 50+ AI voices
+- [OpenClaw](https://openclaw.ai) - AI assistant framework
+
+---
+
+**⭐ If you find AgentVibes useful, please star the repo on GitHub!**
+
+https://github.com/paulpreibisch/AgentVibes
+
+Thank you for using AgentVibes! 🎤✨

package/.mcp.json

@@ -1,38 +1,28 @@
 {
   "mcpServers": {
-    "context7": {
+    "agentvibes": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "--package=agentvibes",
+        "agentvibes-mcp-server"
+      ]
+    },
+    "firecrawl": {
       "command": "npx",
-      "args": ["@upstash/context7-mcp"]
+      "args": [
+        "firecrawl-mcp"
+      ]
     },
-    "sonarqube": {
-      "command": "docker",
+    "context7": {
+      "command": "npx",
       "args": [
-        "run",
-        "-i",
-        "--name",
-        "sonarqube-mcp-server-agentvibes",
-        "--rm",
-        "--dns",
-        "8.8.8.8",
-        "--dns",
-        "8.8.4.4",
-        "-e",
-        "SONARQUBE_TOKEN",
-        "-e",
-        "SONARQUBE_ORG",
-        "-e",
-        "STORAGE_PATH",
-        "mcp/sonarqube"
+        "-y",
+        "@upstash/context7-mcp"
       ],
       "env": {
-        "SONARQUBE_TOKEN": "${SONARQUBE_TOKEN}",
-        "SONARQUBE_ORG": "${SONARQUBE_ORG}",
-        "STORAGE_PATH": "${STORAGE_PATH}"
+        "CONTEXT7_API_KEY": "${CONTEXT7_API_KEY}"
       }
-    },
-    "vercel": {
-      "type": "sse",
-      "url": "https://mcp.vercel.com"
     }
   }
 }

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.6
+**Author**: Paul Preibisch ([@997Fire](https://x.com/997Fire)) | **Version**: v5.6.2
 
 ---
 
@@ -40,7 +40,20 @@ Whether you're coding in Claude Code, chatting in Claude Desktop, using Warp Ter
 
 ---
 
-## 🌟 NEW IN v5.5 — Per-LLM Audio Routing
+## 🌟 NEW IN v5.6.2 — Per-Message Audio Control
+
+Remote senders (Hermes, SSH remote provider) can now control **voice, music, reverb, and volume per message** — no persistent config changes needed. Pass any field in the JSON payload and the Windows receiver applies it for that message only.
+
+## v5.6.1 — Hermes Agent Integration
+
+AgentVibes now speaks for **[Hermes Agent](https://github.com/NousResearch/hermes-agent)** — the self-hosted, self-improving AI assistant. Two production-ready skills ship in `docs/hermes/skills/`:
+
+- **`hermes-agentvibes-hook`** — Auto-speaks every Hermes response via AgentVibes TTS. Fires on `agent:end`, strips markdown, rate-limits, and ships with full SSH MITM protection
+- **`agentvibes-target`** — Teaches Hermes to send any text to your speakers on demand, supporting laptop and Android targets
+
+Also in this release: Windows PS5.1 compatibility fixes for `play-tts.ps1`, modal/hotkey repairs, and BMAD tab now shows all agents.
+
+## v5.5 — Per-LLM Audio Routing
 
 Give **each LLM its own voice, pretext, and music** — Claude Code, Copilot, and Codex can all sound different without touching global settings.
 

package/RELEASE_NOTES.md

@@ -1,5 +1,69 @@
 # AgentVibes Release Notes
 
+## 🎛️ v5.6.2 — Per-Message Audio Control for Remote Providers
+
+**Released:** 2026-05-02
+
+### 🎉 Per-Message Override: Voice, Music, Reverb, Volume
+
+Remote senders (Hermes, SSH remote provider) can now control every audio parameter **per message** without touching the receiver's persistent config:
+
+- **Music** — pass `"music": "bachata"` (keyword) or full filename to switch background track for that message
+- **Volume** — pass `"volume": "0.35"` to adjust music volume for that message  
+- **Reverb** — pass `"effects": "medium"` (`off`/`light`/`medium`/`heavy`/`cathedral`) to set reverb per message
+- **Voice** — already worked; now documented with full field reference
+- **Pretext** — pass `"pretext": ""` to suppress the intro prefix for a single message
+
+Previously these fields were parsed by the receiver and queued but **never applied** — `play-tts.ps1` didn't read the `AGENTVIBES_OVERRIDE_*` env vars the watcher set. Fixed.
+
+### 📚 Hermes Skill: Full Payload Field Reference
+
+`agentvibes-target` SKILL.md now documents all 9 JSON payload fields with examples so Hermes (or any AI agent) can say "switch to chillwave", "add reverb", "use a female voice", "remove the intro prefix" — and it just works.
+
+### 🐛 Hermes Hook: handler.py + HOOK.yaml now ship in the package
+
+`docs/hermes/skills/tts/hermes-agentvibes-hook/` was missing `handler.py` and `HOOK.yaml` — only `SKILL.md` was included. Both files now ship. `handler.py` also reads `AGENTVIBES_MUSIC` from the environment so the default background music is configurable without editing the file.
+
+---
+
+## 🤖 v5.6.1 — Hermes Agent Integration & Windows PS5.1 Fixes
+
+**Released:** 2026-05-01
+
+### 🎉 Hermes Agent Integration (New!)
+
+AgentVibes now officially supports **[Hermes Agent](https://github.com/NousResearch/hermes-agent)** — the self-hosted, self-improving AI assistant. Two production-ready Hermes skills ship in `docs/hermes/skills/`:
+
+**`hermes-agentvibes-hook`** — Auto-speaks every Hermes response via AgentVibes
+- Fires on every `agent:end` event (Telegram, Discord, CLI, etc.)
+- Strips markdown, code blocks, emoji before speaking
+- Truncates at word boundaries, rate-limits to prevent queue flooding
+- MITM-safe SSH with `StrictHostKeyChecking=accept-new` + persistent `known_hosts`
+- Full logging to `tts-hook.log` for debugging
+
+**`agentvibes-target`** — Teaches Hermes to send any text to your speakers on demand
+- Base64 JSON payload over SSH (same ForceCommand architecture as the Windows receiver)
+- Supports Windows and Android targets
+- Detailed troubleshooting guide included
+
+**Install:** Copy the skill to your Hermes home and restart the gateway:
+```bash
+cp -r docs/hermes/skills/tts/hermes-agentvibes-hook ~/.hermes/skills/tts/
+hermes gateway restart
+```
+
+### 🐛 Windows PS5.1 Bug Fixes
+
+- **play-tts.ps1 PS5.1 compatibility** — Fixed three regressions from v5.6.0 rebase:
+  replaced PS7 null-conditional (`?.`) with PS5.1-compatible if/else, added UTF-8 BOM so
+  em-dash literals aren't mangled by CP1252, restored piper provider alias and
+  `AGENTVIBES_TEXT_FILE` sentinel lost in merge
+- **Modal & hotkey fixes** — Modal escape key, navigation hotkeys, Q+Caps Lock, and voice
+  preview error handling all repaired
+- **BMAD tab** — Now shows all agents regardless of module
+
+---
+
 ## 📸 v5.6.0 — TUI Screenshots & Documentation Cleanup
 
 **Released:** 2026-04-28