agentvibes 5.6.0 → 5.6.1

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.1
 
 ---
 
@@ -40,7 +40,16 @@ 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.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,43 @@
 # AgentVibes Release Notes
 
+## 🤖 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

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "agentvibes",
-  "version": "5.6.0",
+  "version": "5.6.1",
   "description": "Now your AI Agents can finally talk back! Professional TTS voice for Claude Code, Claude Desktop (via MCP), and Clawdbot with multi-provider support.",
   "homepage": "https://agentvibes.org",
   "keywords": [

package/src/bmad-detector.js

@@ -1,71 +1,71 @@
-import path from 'node:path';
-import fs from 'node:fs/promises';
-import yaml from 'js-yaml';
-
-/**
- * Detect BMAD installation and version
- * @param {string} targetDir - Directory to check
- * @returns {Promise<Object>} Detection result with version info
- */
-export async function detectBMAD(targetDir) {
-  // Check v6 first (newer version) - support both .bmad and bmad paths
-  // Try .bmad (standard path with dot prefix) first
-  let v6Manifest = path.join(targetDir, '.bmad/_cfg/manifest.yaml');
-  let bmadPath = '.bmad';
-
-  try {
-    await fs.access(v6Manifest);
-  } catch {
-    // Try bmad (alternative path without dot prefix)
-    v6Manifest = path.join(targetDir, 'bmad/_cfg/manifest.yaml');
-    bmadPath = 'bmad';
-    try {
-      await fs.access(v6Manifest);
-    } catch {
-      // Neither path found, continue to v4 check
-      bmadPath = null;
-    }
-  }
-
-  if (bmadPath) {
-    try {
-      const manifestContent = await fs.readFile(v6Manifest, 'utf8');
-      const manifest = yaml.load(manifestContent);
-
-      return {
-        version: 6,
-        detailedVersion: manifest.installation?.version || '6.0.0-alpha.x',
-        manifestPath: v6Manifest,
-        configPath: path.join(targetDir, bmadPath, 'core/config.yaml'),
-        bmadPath: path.join(targetDir, bmadPath),
-        installed: true
-      };
-    } catch {}
-  }
-
-  // Check v4 (legacy)
-  const v4Manifest = path.join(targetDir, '.bmad-core/install-manifest.yaml');
-  try {
-    await fs.access(v4Manifest);
-    return {
-      version: 4,
-      detailedVersion: '4.x',
-      manifestPath: v4Manifest,
-      configPath: path.join(targetDir, '.bmad-core/config.yaml'),
-      bmadPath: path.join(targetDir, '.bmad-core'),
-      installed: true
-    };
-  } catch {}
-
-  // Not installed
-  return { version: null, installed: false };
-}
-
-/**
- * Get BMAD configuration file path for detected version
- * @param {Object} detection - Result from detectBMAD()
- * @returns {string|null} Path to config.yaml or null
- */
-export function getBMADConfigPath(detection) {
-  return detection.installed ? detection.configPath : null;
-}
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import yaml from 'js-yaml';
+
+/**
+ * Detect BMAD installation and version
+ * @param {string} targetDir - Directory to check
+ * @returns {Promise<Object>} Detection result with version info
+ */
+export async function detectBMAD(targetDir) {
+  // Check v6 first (newer version) - support both .bmad and bmad paths
+  // Try .bmad (standard path with dot prefix) first
+  let v6Manifest = path.join(targetDir, '.bmad/_cfg/manifest.yaml');
+  let bmadPath = '.bmad';
+
+  try {
+    await fs.access(v6Manifest);
+  } catch {
+    // Try bmad (alternative path without dot prefix)
+    v6Manifest = path.join(targetDir, 'bmad/_cfg/manifest.yaml');
+    bmadPath = 'bmad';
+    try {
+      await fs.access(v6Manifest);
+    } catch {
+      // Neither path found, continue to v4 check
+      bmadPath = null;
+    }
+  }
+
+  if (bmadPath) {
+    try {
+      const manifestContent = await fs.readFile(v6Manifest, 'utf8');
+      const manifest = yaml.load(manifestContent);
+
+      return {
+        version: 6,
+        detailedVersion: manifest.installation?.version || '6.0.0-alpha.x',
+        manifestPath: v6Manifest,
+        configPath: path.join(targetDir, bmadPath, 'core/config.yaml'),
+        bmadPath: path.join(targetDir, bmadPath),
+        installed: true
+      };
+    } catch {}
+  }
+
+  // Check v4 (legacy)
+  const v4Manifest = path.join(targetDir, '.bmad-core/install-manifest.yaml');
+  try {
+    await fs.access(v4Manifest);
+    return {
+      version: 4,
+      detailedVersion: '4.x',
+      manifestPath: v4Manifest,
+      configPath: path.join(targetDir, '.bmad-core/config.yaml'),
+      bmadPath: path.join(targetDir, '.bmad-core'),
+      installed: true
+    };
+  } catch {}
+
+  // Not installed
+  return { version: null, installed: false };
+}
+
+/**
+ * Get BMAD configuration file path for detected version
+ * @param {Object} detection - Result from detectBMAD()
+ * @returns {string|null} Path to config.yaml or null
+ */
+export function getBMADConfigPath(detection) {
+  return detection.installed ? detection.configPath : null;
+}