Now your AI Agents can finally talk back! Professional TTS voice for Claude Code, Claude Desktop (via MCP), and Clawdbot with multi-provider support.
npm install agentvibes> Finally! Your agents can talk back!
>
> 🌐 agentvibes.org
>
> Professional text-to-speech for Claude Code, Claude Desktop, Warp Terminal, and OpenClaw - Piper TTS (Free!) or macOS Say (Built-in!)
Author: Paul Preibisch (@997Fire) | Version: v3.3.0
---
| I want to... | Go here |
|--------------|---------|
| Install AgentVibes (just npx, no git!) | Quick Start Guide |
| Run Claude Code on Android | Android/Termux Setup |
| Secure OpenClaw on Remote Server | Security Hardening Guide ⚠️ |
| Understand what I need | Prerequisites |
| Set up on Windows (Claude Desktop) | Windows Setup Guide |
| Use with OpenClaw | OpenClaw Integration |
| Use natural language | MCP Setup |
| Switch voices | Voice Library |
| Fix issues (git-lfs? MCP tokens? Read this!) | Troubleshooting & FAQ |
---
AgentVibes adds lively voice narration to your Claude AI sessions!
Whether you're coding in Claude Code, chatting in Claude Desktop, using Warp Terminal, or running OpenClaw - AgentVibes brings AI to life with professional voices and personalities.
✨ NEW IN v3.3.0:
- 📱 AgentVibes Receiver - NEW! - Stream TTS from voiceless servers to your phone, laptop, or local machine via encrypted SSH tunnel
- 🌐 Voiceless Server Support - NEW! - Generate TTS on cloud servers (AWS, GCP, Azure) and play on any device with speakers
⚡ Core Features:
- ⚡ One-Command Install - Get started in 30 seconds (npx agentvibes install)
- 🎭 Multi-Provider Support - Choose Piper TTS (50+ free voices, offline) or macOS Say (100+ built-in)
- 🎙️ 27+ Professional AI Voices - Character voices, accents, and unique personalities
- 🎙️ Verbosity Control - Choose how much Claude speaks (LOW, MEDIUM, HIGH)
- 🎙️ AgentVibes MCP - Natural language control ("Switch to Aria voice") for Claude Code, Desktop & Warp
- 🔊 SSH Audio Optimization - Auto-detects remote sessions and eliminates static (VS Code Remote SSH, cloud dev)
🎭 Personalization:
- 🎭 19 Built-in Personalities - From sarcastic to flirty, pirate to dry humor
- 💬 Advanced Sentiment System - Apply personality styles to ANY voice without changing it
- 🎵 Voice Preview & Replay - Listen before you choose, replay last 10 TTS messages
🚀 Integrations & Power Features:
- 🔌 Enhanced BMAD Plugin - Auto voice switching for BMAD agents with multilingual support
- 🔊 Live Audio Feedback - Hear task acknowledgments and completions in any language
- 🌍 30+ Languages - Multilingual support with native voice quality
- 🆓 Free & Open - Use Piper TTS with no API key required
AgentVibes' Piper TTS uses 100% Hugging Face-trained AI voice models from rhasspy/piper-voices.
What are Hugging Face voice models?
Hugging Face voice models are pre-trained artificial intelligence models hosted on the Hugging Face Model Hub platform, designed to convert text into human-like speech (Text-to-Speech or TTS) or perform other speech tasks like voice cloning and speech-to-speech translation. They're accessible via their Transformers library for easy use in applications like voice assistants, audio generation, and more.
Key Benefits:
- 🎯 Human-like Speech - VITS-based neural models for natural pronunciation and intonation
- 🌍 35+ Languages - Multilingual support with native accents
- 🆓 100% Open Source - All Piper voices are free HF models (Tacotron2, FastSpeech2, VITS)
- 🔧 Developer-Friendly - Fine-tune, customize, or deploy for various audio projects
- ⚡ Offline & Fast - No API keys, no internet needed once installed
All 50+ Piper voices AgentVibes provides are sourced from Hugging Face's open-source AI voice models, ensuring high-quality, natural-sounding speech synthesis across all supported platforms.
---
---
Remote Audio Revolution: Voiceless Servers → Phone & Mobile Playback 📱🔊
AgentVibes v3.3.0 brings breakthrough remote audio capabilities, turning your messaging apps into voice-enabled AI assistants! Use Case: Install OpenClaw on a remote server, message it via Telegram or WhatsApp from anywhere, and AgentVibes (running in Termux on your phone) plays the TTS responses through your phone speakers—making it work like Siri, but powered by AgentVibes! This release enables voiceless servers to play audio remotely on phones, mobile devices, or any machine via SSH/PulseAudio tunneling. Also includes audio tracks directory structure fix and comprehensive OpenClaw skill documentation.
Key Highlights:
- 📱 Voiceless Server Support - Generate TTS on servers without audio hardware, play on remote devices
- 🔊 Phone/Mobile Playback - Audio tunnels from cloud servers to your phone or local machine via SSH
- 🌐 PulseAudio SSH Tunneling - Automatic audio routing through SSH reverse forwarding (port 14713)
- 🤖 Enhanced OpenClaw Integration - Complete skill documentation with 50+ voices and remote audio setup
- 🎵 Audio Tracks Fix - Corrected directory structure (backgrounds → tracks) with proper .npmignore entries
- 📦 Package Size Optimization - 8.3 MB unpacked, 172 files, optimized for npm distribution
- 🛡️ Security & Quality - Removed sensitive data from git history, SonarCloud compliance
Perfect For:
- Running AgentVibes/OpenClaw on AWS, GCP, Azure, DigitalOcean
- VS Code Remote SSH development with TTS feedback
- Android/Termux with audio playback on phone speakers
- Any headless server → local audio scenario
💡 Tip: If npx agentvibes shows an older version or missing commands, clear your npm cache: npm cache clean --force && npx agentvibes@latest --help
🐛 Found a bug? Report issues at GitHub Issues
---
Agent Vibes was originally created to give the Claude Code assistant a voice! Simply install it with an npx command in your terminal, and Claude Code can talk back to you.
We've now enhanced this capability by adding an MCP (Model Context Protocol) server. This integration exposes Agent Vibes' functionality directly to your AI assistant, allowing you to configure and control Agent Vibes using natural language instead of typing "/" slash commands.
Setting it up is straightforward: just add the MCP server to your Claude Code configuration files.
But the convenience doesn't stop there. With the MCP server in place, Claude Desktop can now use Agent Vibes too! We've even tested it successfully with Warp, an AI assistant that helps you navigate Windows and other operating systems.
We're thrilled about this expansion because it means Claude Desktop and Warp can finally talk back as well!
If you decide to use the MCP server on Claude Desktop, after configuration, give Claude Desktop this command: "every time i give you a command, speak the acknowledgement using agentvibes and the confirmation about what you completed, when done"—and watch the magic happen!
🎯 Control AgentVibes with natural language - no slash commands to remember!
Just say "Switch to Aria voice" or "Speak in Spanish" instead of typing commands.
Works in: Claude Desktop, Claude Code, Warp Terminal
→ View Complete MCP Setup Guide - Full setup for all platforms, configuration examples, available tools, and MCP vs slash commands comparison
---
3 Simple Steps:
bash
npx agentvibes install
`$3
- macOS: Native provider (100+ voices) ✨
- Linux/WSL: Piper TTS (50+ free voices) 🎙️
- Android: Termux with auto-setup 📱$3
Just code normally - AgentVibes automatically speaks task acknowledgments and completions! 🔊---
🍎 macOS Users (One-Time Setup):
`bash
brew install bash # Required for bash 5.x features
`
macOS ships with bash 3.2 (from 2007). After this, everything works perfectly!---
→ Full Setup Guide - Advanced options, provider switching, and detailed setup
---
📋 Prerequisites - What You Actually Need
$3
✅ REQUIRED:
- Node.js ≥16.0 - Check with: $3
✅ STRONGLY RECOMMENDED:
- Python 3.10+ - Needed for Piper TTS voice engine
- bash 5.0+ - macOS only (macOS ships with 3.2 from 2007)$3
⭕ OPTIONAL (TTS still works without them):
- sox - Audio effects (reverb, EQ, pitch shifting)
- ffmpeg - Background music, audio padding, RDP compression$3
❌ DEFINITELY NOT NEEDED:
- ❌ Git or git-lfs (npm handles everything)
- ❌ Repository cloning (unless you're contributing code)
- ❌ Build tools or C++ compilers (pre-built package ready to use)$3
| Method | Command | Use Case |
|--------|---------|----------|
| ✅ RECOMMENDED: NPX (via npm) |
| Users - Just want to use AgentVibes |
| ⚠️ Git Clone | git clone ... | Developers Only - Contributing code |Why npx? Zero git operations, no build steps, just 30 seconds to voice!
$3
If you want to contribute to AgentVibes:
`bash
git clone https://github.com/paulpreibisch/AgentVibes.git
cd AgentVibes
npm install
npm link
`Requires: Node.js 16+, Git (no git-lfs), and
familiarity.---
---
📱 Quick Setup: Android & Termux (Claude Code on Your Phone!)
Want to run Claude Code on your Android phone with professional voices?
Simply install Termux from F-Droid (NOT Google Play) and run:
`bash
pkg update && pkg upgrade
pkg install nodejs-lts
npx agentvibes install
`Termux auto-detects and installs everything needed (proot-distro for compatibility, Piper TTS, audio playback).
→ Full Android/Termux Setup Guide - Detailed troubleshooting and verification steps
---
📋 System Requirements
AgentVibes requires certain system dependencies for optimal audio processing and playback. Requirements vary by operating system and TTS provider.
$3
| Tool | Required For | Why It's Needed |
|------|-------------|-----------------|
| Node.js ≥16.0 | All platforms | Runtime for AgentVibes installer and MCP server |
| Bash ≥5.0 | macOS | Modern bash features (macOS ships with 3.2 from 2007) |
| Python 3.10+ | Piper TTS, MCP server | Runs Piper voice engine and MCP server |
$3
| Tool | Status | Purpose | Impact if Missing |
|------|--------|---------|------------------|
| sox | Recommended | Audio effects (reverb, EQ, pitch, compression) | No audio effects, still works |
| ffmpeg | Recommended | Background music mixing, audio padding, RDP compression | No background music or RDP optimization |
$3
#### 🐧 Linux / WSL
bash
Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y sox ffmpeg python3-pip pipxFedora/RHEL
sudo dnf install -y sox ffmpeg python3-pip pipxArch Linux
sudo pacman -S sox ffmpeg python-pip python-pipx
`Audio Playback (one of the following):
-
(PulseAudio - usually pre-installed)
- aplay (ALSA - fallback)
- mpg123 (fallback)
- mpv (fallback)Why these tools?
- sox: Applies audio effects defined in
.claude/config/audio-effects.cfg (reverb, pitch shifting, EQ, compression)
- ffmpeg: Mixes background music tracks, adds silence padding to prevent audio cutoff, compresses audio for RDP/SSH sessions
- paplay/aplay: Plays generated TTS audio files
- pipx: Isolated Python environment manager for Piper TTS installation#### 🍎 macOS
`bash
Install Homebrew if not already installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"Required: Modern bash
brew install bashRecommended: Audio processing tools
brew install sox ffmpeg pipx
`Audio Playback:
-
(built-in - always available)
- say (built-in - for macOS TTS provider)Why these tools?
- bash 5.x: macOS ships with bash 3.2 which lacks associative arrays and other modern features AgentVibes uses
- sox: Same audio effects processing as Linux
- ffmpeg: Same background music and padding as Linux
- afplay: Built-in macOS audio player
- say: Built-in macOS text-to-speech (alternative to Piper)
#### 🪟 Windows (WSL Required)
AgentVibes requires WSL (Windows Subsystem for Linux) on Windows. Follow the Windows Setup Guide for complete installation.
`powershell
Install WSL from PowerShell (Administrator)
wsl --install -d Ubuntu
`Then follow Linux requirements above inside WSL.
Why WSL?
- AgentVibes uses bash scripts extensively
- Audio routing from WSL to Windows requires PulseAudio configuration
- See Windows Setup Guide for detailed audio setup
#### 🤖 Android / Termux
Running Claude Code on Your Android Using Termux
AgentVibes fully supports Android devices through the Termux app. This enables you to run Claude Code with professional TTS voices directly on your Android phone or tablet!
Quick Setup:
bash
1. Install Termux from F-Droid (NOT Google Play - it's outdated)
Download: https://f-droid.org/en/packages/com.termux/
2. Install Node.js in Termux
pkg update && pkg upgrade
pkg install nodejs-lts3. Install AgentVibes (auto-detects Android and runs Termux installer)
npx agentvibes install
`What Gets Installed?
The Termux installer automatically sets up:
- proot-distro with Debian (for glibc compatibility)
- Piper TTS via proot wrapper (Android uses bionic libc, not glibc)
- termux-media-player for audio playback (
doesn't work on Android)
- Audio dependencies: ffmpeg, sox, bc for processing
- termux-api for Android-specific audio routingWhy Termux Instead of Standard Installation?
Android's architecture requires special handling:
- ❌ Standard pip/pipx fails (missing wheels for bionic libc)
- ❌ Linux binaries require glibc (Android uses bionic)
- ❌
/tmp directory is not accessible on Android
- ❌ Standard audio tools like paplay don't exist✅ Termux installer solves all these issues with proot-distro and Android-native audio playback!
Requirements:
- Termux app (from F-Droid, NOT Google Play)
- Termux:API (for audio playback)
- Android 7.0+ (recommended: Android 10+)
- ~500MB free storage (for Piper TTS + voice models)
Audio Playback:
- Uses
termux-media-player instead of paplay
- Audio automatically routes through Android's media system
- Supports all Piper TTS voices (50+ languages)Verifying Your Setup:
bash
Check Termux environment
echo $PREFIX # Should show /data/data/com.termux/files/usrCheck Node.js
node --version # Should be ≥16.0Check if Piper is installed
which piper # Should return /data/data/com.termux/files/usr/bin/piperTest audio playback
termux-media-player play /path/to/audio.wav
`Troubleshooting:
| Issue | Solution |
|-------|----------|
| "piper: not found" | Run
- auto-detects Termux |
| No audio playback | Install Termux:API from F-Droid |
| Permission denied | Run termux-setup-storage to grant storage access |
| Slow installation | Use WiFi, not mobile data (~300MB download) |Why F-Droid and Not Google Play?
Google Play's Termux version is outdated and unsupported. Always use the F-Droid version for the latest security updates and compatibility.
$3
#### Piper TTS (Free, Offline)
- Python 3.10+
- pipx (for isolated installation)
- Disk Space: ~50MB per voice model
- Internet: Only for initial voice downloads
`bash
Installed automatically by AgentVibes
pipx install piper-tts
`#### macOS Say (Built-in, macOS Only)
- No additional requirements
- 100+ voices pre-installed on macOS
- Use:
$3
bash
Check all dependencies
node --version # Should be ≥16.0
python3 --version # Should be ≥3.10
bash --version # Should be ≥5.0 (macOS users!)
sox --version # Optional but recommended
ffmpeg -version # Optional but recommended
pipx --version # Required for Piper TTSCheck audio playback (Linux/WSL)
paplay --version || aplay --versionCheck audio playback (macOS)
which afplay # Should return /usr/bin/afplay
`$3
| Missing Tool | Impact | Workaround |
|-------------|--------|------------|
| sox | No audio effects (reverb, EQ, pitch) | TTS still works, just no effects |
| ffmpeg | No background music, no audio padding | TTS still works, audio may cut off slightly early |
| paplay/aplay | No audio playback on Linux | Install at least one audio player |
All TTS generation still works - optional tools only enhance the experience!
---
🎭 Choose Your Voice Provider
Piper TTS (free, works offline on Linux/WSL) or macOS Say (free, built-in on Mac) - pick one and switch anytime.
| Provider | Platform | Cost | Quality | Setup |
|----------|----------|------|---------|-------|
| macOS Say | macOS only | Free (built-in) | ⭐⭐⭐⭐ | Zero config |
| Piper | Linux/WSL | Free | ⭐⭐⭐⭐ | Auto-downloads |
On macOS, the native
provider is automatically detected and recommended!---
🎤 Commands Reference
AgentVibes provides 50+ slash commands and natural language MCP equivalents.
Quick Examples:
`bash
Voice control
/agent-vibes:switch Aria # Or: "Switch to Aria voice"
/agent-vibes:list # Or: "List all voices"Personality & sentiment
/agent-vibes:personality pirate # Or: "Set personality to pirate"
/agent-vibes:sentiment sarcastic # Or: "Apply sarcastic sentiment"Language & learning
/agent-vibes:set-language spanish # Or: "Speak in Spanish"
/agent-vibes:learn # Or: "Enable learning mode"
`→ View Complete Command Reference - All voice, system, personality, sentiment, language, and BMAD commands with MCP equivalents
---
🎙️ Verbosity Control
Control how much Claude speaks while working! 🔊
Choose from three verbosity levels:
$3
- Acknowledgments only (start of task)
- Completions only (end of task)
- Perfect for quiet work sessions$3
- Acknowledgments + completions
- Major decisions ("I'll use grep to search")
- Key findings ("Found 12 instances")
- Perfect for understanding decisions without full narration$3
- All reasoning ("Let me search for all instances")
- All decisions ("I'll use grep for this")
- All findings ("Found it at line 1323")
- Perfect for learning mode, debugging complex tasksQuick Commands:
bash
/agent-vibes:verbosity # Show current level
/agent-vibes:verbosity high # Maximum transparency
/agent-vibes:verbosity medium # Balanced
/agent-vibes:verbosity low # Minimal (default)
`MCP Equivalent:
"Set verbosity to high"
"What's my current verbosity level?"
💡 How it works: Claude uses emoji markers (💭 🤔 ✓) in its text, and AgentVibes automatically detects and speaks them based on your verbosity level. No manual TTS calls needed!
⚠️ Note: Changes take effect on next Claude Code session restart.
---
📚 Language Learning Mode
🎯 Learn Spanish (or 30+ languages) while you program! 🌍
Every task acknowledgment plays twice - first in English, then in your target language. Context-based learning while you code!
→ View Complete Learning Mode Guide - Full tutorial, quick start, commands, speech rate control, supported languages, and pro tips
---
🎭 Personalities vs Sentiments
Two ways to add personality:
- 🎪 Personalities - Changes BOTH voice AND speaking style (e.g.,
personality = Pirate Marshal voice + pirate speak)
- 💭 Sentiments - Keeps your current voice, only changes speaking style (e.g., Aria voice + sarcastic sentiment)→ Complete Personalities Guide - All 19 personalities, create custom ones
---
🗣️ Voice Library
AgentVibes includes professional AI voices from Piper TTS and macOS Say with multilingual support.
🎧 Try in Claude Code:
/agent-vibes:preview to hear all voices
🌍 Multilingual: Use Antoni, Rachel, Domi, or Bella for automatic language detection→ View Complete Voice Library - All 27 voices with clickable samples, descriptions, and best use cases
---
🔌 BMAD Plugin
Automatically switch voices when using BMAD agents!
The BMAD plugin detects when you activate a BMAD agent (e.g.,
/BMad:agents:pm) and automatically uses the assigned voice for that role.Version Support: AgentVibes supports both BMAD v4 and v6-alpha installations. Version detection is automatic - just install BMAD and AgentVibes will detect and configure itself correctly!
$3
BMAD uses a loosely-coupled injection system for voice integration. BMAD source files contain placeholder markers that AgentVibes replaces with speaking instructions during installation:
Before Installation (BMAD Source):
`xml
ALWAYS communicate in {communication_language}...
Stay in character until exit selected
`After Installation (with AgentVibes enabled):
xml
ALWAYS communicate in {communication_language}...
- When responding to user messages, speak your responses using TTS:
Call: .claude/hooks/bmad-speak.sh '{agent-id}' '{response-text}'
Where {agent-id} is your agent type (pm, architect, dev, etc.) - Auto Voice Switching: AgentVibes automatically switches to the voice
assigned for your agent role when activated
Stay in character until exit selected
After Installation (with TTS disabled):
xml
ALWAYS communicate in {communication_language}...
Stay in character until exit selected
`This design means any TTS provider can integrate with BMAD by replacing these markers with their own instructions!
→ View Complete BMAD Documentation - All agent mappings, language support, TTS injection details, plugin management, and customization
---
🤖 OpenClaw Integration
Use AgentVibes TTS with OpenClaw - the revolutionary AI assistant you can access via any instant messenger!
What is OpenClaw? OpenClaw is a revolutionary AI assistant that brings Claude AI to your favorite messaging platforms - WhatsApp, Telegram, Discord, and more. No apps to install, no websites to visit - just message your AI assistant like you would a friend.
🌐 Website: https://openclaw.ai/
AgentVibes seamlessly integrates with OpenClaw, providing professional text-to-speech for AI assistants running on messaging platforms and remote servers.
$3
⚠️ SECURITY IS NOT OPTIONAL - Running OpenClaw on a remote server exposes your infrastructure to attack vectors including SSH compromise, credential theft, and lateral movement.
👉 READ THIS FIRST: Security Hardening Guide - Required reading covering:
- ✅ SSH hardening (key-only auth, port 2222, fail2ban)
- ✅ Firewall configuration (UFW/iptables)
- ✅ Intrusion detection (AIDE, Wazuh)
- ✅ VPN tunneling (Tailscale alternative to direct SSH)
Do not expose your OpenClaw server to the internet without reading this guide.
$3
- Free & Offline: No API costs, works without internet
- Remote SSH Audio: Audio tunnels from server to local machine via PulseAudio
- 50+ Voices: Professional AI voices in 30+ languages
- Zero Config: Automatic when AgentVibes is installed
$3
AgentVibes includes a ready-to-use OpenClaw skill that enables TTS on messaging platforms. The setup involves two components:
#### Component 1: OpenClaw Server (Remote)
Install AgentVibes on your OpenClaw server:
bash
On your remote server where OpenClaw is running
npx agentvibes install
`The OpenClaw skill is automatically included in the AgentVibes npm package at
.How to activate the skill in OpenClaw:
1. Locate the skill - After installing AgentVibes, the skill is at:
`
node_modules/agentvibes/.clawdbot/skill/SKILL.md
2. Link to OpenClaw skills directory (if OpenClaw uses skills):
bash
# Example - adjust path based on your OpenClaw installation
ln -s $(npm root -g)/agentvibes/.clawdbot/skill/SKILL.md ~/.openclaw/skills/agentvibes.md
`3. OpenClaw auto-detection - Many OpenClaw setups automatically detect AgentVibes when it's installed. Check your OpenClaw logs for:
✓ AgentVibes skill detected and loaded
---
#### 🎙️ AgentVibes Voice Management Skill for OpenClaw
Manage your text-to-speech voices across multiple providers with the AgentVibes Voice Management Skill:
Voice Management Features:
- 🎤 50+ Professional Voices - Across Piper TTS, Piper (free offline), and macOS Say providers
- 🔀 Multi-Provider Support - Switch between Piper TTS (premium), Piper (free), and macOS Say
- 👂 Voice Preview - Listen to voices before selecting them
- 🎚️ Voice Customization - Add custom voices, set pretext, control speech rate
- 📋 Voice Management - List, switch, replay, and manage your voice library
- 🔇 Mute Control - Mute/unmute TTS output with persistent settings
- 🌍 Multilingual Support - Voices in 30+ languages across all providers
Installation Confirmation:
✅ The skill is automatically included in the AgentVibes npm package at:
node_modules/agentvibes/.clawdbot/skill/SKILL.md
No extra setup needed - when you run
on your OpenClaw server, the skill is ready to use!Full Skill Documentation:
→ View Complete AgentVibes Skill Guide - 430+ lines covering:
- Quick start with 50+ voice options
- Background music & effects management
- Personality system (19+ styles)
- Voice effects (reverb, reverb, EQ)
- Speed & verbosity control
- Remote SSH audio setup
- Troubleshooting & complete reference
Popular Voice Examples:
`bash
Female voices
npx agentvibes speak "Hello" --voice en_US-amy-medium
npx agentvibes speak "Bonjour" --voice fr_FR-siwis-mediumMale voices
npx agentvibes speak "Hello" --voice en_US-lessac-medium
npx agentvibes speak "Good day" --voice en_GB-alan-mediumAdd personality!
bash ~/.claude/hooks/personality-manager.sh set sarcastic
bash ~/.claude/hooks/play-tts.sh "Oh wonderful, another request"
`---
#### Component 2: AgentVibes Receiver (Local/Phone) ⚠️ REQUIRED
CRITICAL: You MUST install AgentVibes on your phone (or local machine) to receive and play audio!
Without this, audio cannot be heard - the server generates TTS but needs a receiver to play it.
Install on Android Phone (Termux):
1. Install Termux from F-Droid (NOT Google Play):
- Download: https://f-droid.org/en/packages/com.termux/
2. Install Node.js in Termux:
bash
pkg update && pkg upgrade
pkg install nodejs-lts
`3. Install AgentVibes in Termux:
bash
npx agentvibes install
`4. Install Termux:API (for audio playback):
- Download: https://f-droid.org/en/packages/com.termux.api/
- Then in Termux:
Install on Local Mac/Linux:
bash
npx agentvibes install
`Why is this needed?
- The server generates TTS but has no speakers (headless)
- AgentVibes on your phone acts as the audio receiver via SSH tunnel
- Audio tunnels from server → SSH → phone → speakers 🔊
Without AgentVibes installed on the receiving device, you'll generate audio but hear nothing!
#### How It Works: Server → SSH Tunnel → Local Playback
┌─────────────────────────────────────────────────────────┐
│ 1. User messages OpenClaw via Telegram/WhatsApp │
│ "Tell me about the weather" │
└─────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────┐
│ 2. OpenClaw (Server) processes request with Claude │
│ AgentVibes skill generates TTS audio │
└─────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────┐
│ 3. Audio tunnels through SSH → PulseAudio (port 14713)│
│ Server: PULSE_SERVER=tcp:localhost:14713 │
└─────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────┐
│ 4. Local AgentVibes receives and plays audio │
│ Phone speakers, laptop speakers, etc. │
│ 🔊 "The weather is sunny and 72 degrees" │
└─────────────────────────────────────────────────────────┘
Architecture:
- Server (OpenClaw): Generates TTS, sends via PulseAudio
- SSH Tunnel: RemoteForward port 14713 (encrypted transport)
- Local (Termux/Desktop): AgentVibes receives audio, plays on speakers
This creates a Siri-like experience - message from anywhere, hear responses on your phone! 📱🎤
$3
#### Basic TTS Commands
bash
Basic TTS
npx agentvibes speak "Hello from OpenClaw"With different voices
npx agentvibes speak "Hello" --voice en_US-amy-medium
npx agentvibes speak "Bonjour" --voice fr_FR-siwis-mediumList available voices
npx agentvibes voices
`#### Advanced: Direct Hook Usage with Voice Override
For programmatic control, use the TTS hook directly:
bash
Basic: Use default voice
bash ~/.claude/hooks/play-tts.sh "Hello from OpenClaw"Advanced: Override voice per message
bash ~/.claude/hooks/play-tts.sh "Welcome message" "en_US-amy-medium"
bash ~/.claude/hooks/play-tts.sh "Bonjour!" "fr_FR-siwis-medium"
bash ~/.claude/hooks/play-tts.sh "British greeting" "en_GB-alan-medium"
`Parameters:
-
- TEXT (required): Message to speak
- $2 - VOICE (optional): Voice name to override default#### Audio Effects Configuration for OpenClaw
File:
.claude/config/audio-effects.cfgCustomize audio effects, background music, and voice processing per agent or use default settings:
Format:
AGENT_NAME|SOX_EFFECTS|BACKGROUND_FILE|BACKGROUND_VOLUME
Example Configuration:
bash
Default - subtle background music
default||agentvibes_soft_flamenco_loop.mp3|0.30Custom agent with reverb + background
MyAgent|reverb 40 50 90 gain -2|agentvibes_soft_flamenco_loop.mp3|0.20Agent with pitch shift and EQ
Assistant|pitch -100 equalizer 3000 1q +2|agentvibes_dark_chill_step_loop.mp3|0.15
`Available SOX Effects:
| Effect | Syntax | Example | Description |
|--------|--------|---------|-------------|
| Reverb |
| reverb 40 50 90 | Adds room ambiance (light: 30 40 70, heavy: 50 60 100) |
| Pitch | pitch | pitch -100 | Shift pitch (100 cents = 1 semitone, negative = lower) |
| Equalizer | equalizer | equalizer 3000 1q +2 | Boost/cut frequencies (bass: 200Hz, treble: 4000Hz) |
| Gain | gain | gain -2 | Adjust volume (negative = quieter, positive = louder) |
| Compand | compand | compand 0.3,1 6:-70,-60,-20 | Dynamic range compression (makes quiet parts louder) |Background Music Tracks:
Built-in tracks available in
.claude/audio/tracks/:
- agentvibes_soft_flamenco_loop.mp3 - Warm, rhythmic flamenco
- agentvibes_dark_chill_step_loop.mp3 - Modern chill electronic
- (50+ additional tracks available)Background Volume:
-
0.10 - Very subtle (10%)
- 0.20 - Subtle (20%)
- 0.30 - Moderate (30%, recommended default)
- 0.40 - Noticeable (40%, party mode)Example: OpenClaw Custom Configuration
Create
.claude/config/audio-effects.cfg on your OpenClaw server:`bash
OpenClaw assistant - warm voice with subtle reverb
OpenClaw|reverb 30 40 70 gain -1|agentvibes_soft_flamenco_loop.mp3|0.25Help desk agent - clear, bright voice
HelpDesk|equalizer 4000 1q +3 compand 0.2,0.5 6:-70,-60,-20|agentvibes_dark_chill_step_loop.mp3|0.15Default fallback
default||agentvibes_soft_flamenco_loop.mp3|0.30
`How AgentVibes Applies Effects:
1. Generate TTS - Create base audio with Piper TTS
2. Apply SOX effects - Process audio (reverb, EQ, pitch, etc.)
3. Mix background - Blend background music at specified volume
4. Tunnel via SSH - Send processed audio to local receiver
5. Play on device - Output to phone/laptop speakers
This allows per-message customization or consistent agent branding with unique audio signatures!
$3
Perfect for running OpenClaw on a remote server with audio on your local machine:
Quick Setup:
1. Remote server - Configure PulseAudio:
bash
echo 'export PULSE_SERVER=tcp:localhost:14713' >> ~/.bashrc
source ~/.bashrc
`2. Local machine - Add SSH tunnel (
):
`
Host your-server
RemoteForward 14713 localhost:14713
3. Connect and test:
bash
ssh your-server
agentvibes speak "Testing remote audio from OpenClaw"
`Audio plays on your local speakers! 🔊
$3
- OpenClaw Skill: .clawdbot/README.md
- OpenClaw Website: https://openclaw.ai/
- Remote Audio Setup: docs/remote-audio-setup.md
- Security Hardening: docs/security-hardening-guide.md ⚠️
---
🎙️ AgentVibes Receiver: Remote Audio Streaming from Voiceless Servers
Receive and play TTS audio from servers that have no audio output!
AgentVibes Receiver is a lightweight audio client that runs on your phone, tablet, or personal computer, which receives TTS audio from remote voiceless servers, where your OpenClaw Personal Assistant or your Claude Code project is installed.
$3
You have OpenClaw running on a Mac mini or remote server with no audio output:
- 🖥️ Mac mini (silent)
- 🖥️ Ubuntu server (headless)
- ☁️ AWS/DigitalOcean instance
- 📦 Docker container
- 🪟 WSL (Windows Subsystem for Linux)
Users message you via WhatsApp, Telegram, Discord but only get text responses:
- ❌ No voice = Less engaging experience
- ❌ No personality = Feels robotic
- ❌ No audio cues = Miss important context
AgentVibes Receiver transforms this:
- ✅ OpenClaw speaks with voice (Siri-like experience)
- ✅ Audio streams to your device automatically
- ✅ You hear responses on your speakers
- ✅ Users get a conversational AI experience
$3
One-time setup:
1. Install AgentVibes on your voiceless server with OpenClaw
2. Install AgentVibes Receiver on your personal device (phone/tablet/laptop)
3. Connect via SSH tunnel (or Tailscale VPN)
4. Done - automatic from then on
Flow diagram:
┌──────────────────────────────────────────┐
│ Your Mac mini / Server │
│ (OpenClaw + AgentVibes) │
│ • Generates TTS audio │
│ • Sends via SSH tunnel │
└──────────────────────────────────────────┘
↓ Encrypted SSH tunnel
┌──────────────────────────────────────────┐
│ Your Phone / Laptop │
│ (AgentVibes Receiver) │
│ • Receives audio stream (or text stream) │
│ • Auto-plays on device speakers │
└──────────────────────────────────────────┘
Real-world example:
📱 WhatsApp: "Tell me about quantum computing"
↓
🖥️ Mac mini: OpenClaw processes + generates TTS
↓ SSH tunnel (audio or text stream)
📱 Your phone (Agent Vibes Receiver): Plays audio 🔊
↓
You hear on your device speakers: "Quantum computing uses quantum bits..."
↓
💬 Conversation feels alive!
$3
| Feature | Benefit |
|---------|---------|
| One-Time Pairing | SSH key setup, automatic reconnect |
| Real-Time Streaming | Low-latency audio playback |
| SSH Encryption | Secure audio tunnel |
| Tailscale Support | Easy VPN for remote servers |
| Voice Selection | Configure server-side voice |
| Audio Effects | Reverb, echo, pitch on server |
| Cache Tracking | Monitor audio generation |
| Multiple Servers | Connect to different OpenClaw instances |
$3
- 🖥️ Mac mini + OpenClaw - Home server with professional voices
- ☁️ Remote Servers - OpenClaw on AWS/GCP/DigitalOcean
- 📱 WhatsApp/Telegram - Users message, hear responses
- 🎓 Discord Bots - Bot speaks with voices
- 🏗️ Docker/Containers - Containerized OpenClaw with audio
- 🔧 WSL Development - Windows developers using voiceless WSL
$3
bash
On your server (Mac mini, Ubuntu, AWS, etc.)
npx agentvibes install
Selects OpenClaw option
AgentVibes installs with SSH-Remote provider
On your personal device (phone, laptop, tablet)
npx agentvibes receiver setup
Pairing prompt with server SSH key
Done!
`$3
→ View AgentVibes Receiver Setup Guide - Pairing, SSH configuration, Tailscale setup, troubleshooting
→ View OpenClaw Integration Guide - Server setup, voice configuration, audio effects, and best practices
---
📦 Installation Structure
What gets installed: Commands, hooks, personalities, and plugins in
directory.→ View Complete Installation Structure - Full directory tree, file descriptions, and settings storage
---
💡 Common Workflows
`bash
Switch voices
/agent-vibes:list # See all voices
/agent-vibes:switch Aria # Change voiceTry personalities
/agent-vibes:personality pirate # Pirate voice + style
/agent-vibes:personality list # See all 19 personalitiesSpeak in other languages
/agent-vibes:set-language spanish # Speak in Spanish
/agent-vibes:set-language list # See 30+ languagesReplay audio
/agent-vibes:replay # Replay last message
`💡 Tip: Using MCP? Just say "Switch to Aria voice" or "Speak in Spanish" instead of typing commands.
---
🔧 Advanced Features
AgentVibes supports custom personalities and custom voices.
Quick Examples:
bash
Create custom personality
/agent-vibes:personality add mycustomAdd custom Piper voice
/agent-vibes:add "My Voice" abc123xyz789Use in custom output styles
[Bash: .claude/hooks/play-tts.sh "Starting" "Aria"]
`→ View Advanced Features Guide - Custom personalities, custom voices, and more
---
🔊 Remote Audio Setup
Running AgentVibes on a remote server? No problem!
✅ Auto-detects SSH sessions - Works with VS Code Remote SSH, regular SSH, cloud dev environments
✅ Zero configuration - Audio optimizes automatically
✅ No static/clicking - Clean playback through SSH tunnels
→ Remote Audio Setup Guide - Full PulseAudio configuration details
---
🔗 Useful Links
$3
- 🎤 WhisperTyping - Fast voice-to-text typing for developers
- 🗣️ OpenWhisper (Azure) - Microsoft's speech-to-text service
- 🆓 Piper TTS - Free offline neural TTS
- 🤖 Claude Code - AI coding assistant
- 🎭 BMAD METHOD - Multi-agent framework
$3
- 🐛 Issues - Report bugs
- 📝 Changelog - Version history
- 📰 Technical Deep Dive - LinkedIn Article - How AgentVibes works under the hood
---
❓ Troubleshooting
Common Issues:
❌ Error: "git-lfs is not installed"
AgentVibes does NOT require git-lfs. This error suggests:
1. Wrong installation method - Use npm, not git clone:
bash
# ✅ CORRECT - Use this:
npx agentvibes install # ❌ WRONG - Don't clone unless contributing:
git clone https://github.com/paulpreibisch/AgentVibes.git
`2. Different project - You may be in a BMAD-METHOD or other repo that uses git-lfs
3. Global git config - Your git may have lfs enabled globally:
bash
git config --global --list | grep lfs
`Solution: Use
- no git operations needed!---
No Audio Playing?
1. Verify hook is installed:
ls -la .claude/hooks/session-start-tts.sh
2. Test: Commands Not Found?
bash
npx agentvibes install --yes
`→ View Complete Troubleshooting Guide - Solutions for audio issues, command problems, MCP errors, voice issues, and more
---
🔄 Updating
Quick Update (From Claude Code):
bash
/agent-vibes:update
`Alternative Methods:
bash
Via npx
npx agentvibes update --yesVia npm (if installed globally)
npm update -g agentvibes && agentvibes update --yes
`Check Version:
→ View Complete Update Guide - All update methods, version checking, what gets updated, and troubleshooting
---
🗑️ Uninstalling
Quick Uninstall (Project Only):
bash
npx agentvibes uninstall
`Uninstall Options:
bash
Interactive uninstall (confirms before removing)
npx agentvibes uninstallAuto-confirm (skip confirmation prompt)
npx agentvibes uninstall --yesAlso remove global configuration
npx agentvibes uninstall --globalComplete uninstall including Piper TTS
npx agentvibes uninstall --global --with-piper
`What Gets Removed:
Project-level (default):
-
- Slash commands
- .claude/hooks/ - TTS scripts
- .claude/personalities/ - Personality templates
- .claude/output-styles/ - Output styles
- .claude/audio/ - Audio cache
- .claude/tts-*.txt - TTS configuration files
- .agentvibes/ - BMAD integration filesGlobal (with
--global flag):
- ~/.claude/ - Global configuration
- ~/.agentvibes/ - Global cachePiper TTS (with
--with-piper flag):
- ~/piper/ - Piper TTS installationTo Reinstall:
`bash
npx agentvibes install
`💡 Tips:
- Default uninstall only removes project-level files
- Use
if you want to completely reset AgentVibes
- Use --with-piper if you also want to remove the Piper TTS engine
- Run npx agentvibes status to check installation status---
❓ Frequently Asked Questions (FAQ)
$3
Q: Does AgentVibes require git-lfs?
A: NO. AgentVibes has zero git-lfs requirement. Use
npx agentvibes install - no git operations needed.Q: Do I need to clone the GitHub repository?
A: NO (unless you're contributing code). Normal users should use
npx agentvibes install. Repository cloning is only for developers who want to contribute to the project.Q: Why is the GitHub repo so large?
A: The repo includes demo files and development dependencies (node_modules). The actual npm package you download is < 50MB and optimized for users.
Q: What's the difference between npm install and git clone?
A:
-
npx agentvibes install → For users - Downloads pre-built package, zero git operations, instant setup
- git clone ... → For developers only - Full source code, development setup, contributing codeQ: I saw an error about git-lfs, is something wrong?
A: You're likely:
1. Using wrong installation method (use
npx not git clone)
2. In a different project directory that uses git-lfs
3. Have global git config with lfs enabledAgentVibes itself does NOT use or require git-lfs.
$3
Q: Does MCP consume tokens from my context window?
A: YES. Every MCP tool schema adds to the context window. AgentVibes MCP is designed to be minimal (~1500-2000 tokens), but if you're concerned about token usage, you can use slash commands instead of MCP.
Q: What's the difference between using MCP vs slash commands?
A:
- MCP: Natural language ("Switch to Aria voice"), uses ~1500-2000 context tokens
- Slash commands: Explicit commands (
/agent-vibes:switch Aria), zero token overheadBoth do the exact same thing - MCP is more convenient, slash commands are more token-efficient.
Q: Is AgentVibes just a bash script?
A: No. AgentVibes includes:
- Multi-provider TTS abstraction (Piper TTS, macOS Say)
- Voice management system with 50+ voices
- Personality & sentiment system
- Language learning mode with bilingual playback
- Audio effects processing (reverb, EQ, compression)
- MCP server for natural language control
- BMAD integration for multi-agent voice switching
- Remote audio optimization for SSH/RDP sessions
Q: Can I use AgentVibes without BMAD?
A: YES. AgentVibes works standalone. BMAD integration is optional - only activates if you install BMAD separately.
Q: What are the audio dependencies?
A:
- Required: Node.js 16+, Python 3.10+ (for Piper TTS)
- Optional: sox (audio effects), ffmpeg (background music, padding)
- All TTS generation works without optional dependencies - they just enhance the experience
$3
Q: Why isn't Claude speaking?
A: Common causes:
1. Hook not installed - Run
npx agentvibes install --yes
2. Audio player missing - Install and ffmpeg
3. TTS protocol not enabled in settings
4. Test with Q: Can I use this on Windows?
A: Yes, but requires WSL (Windows Subsystem for Linux). See Windows Setup Guide.
Q: How do I reduce token usage?
A:
1. Use slash commands instead of MCP (zero context token overhead)
2. Set verbosity to LOW (
---
API Costs & Usage:
- Usage is completely free with Piper TTS and Mac Say (no API costs)
- Users are solely responsible for their own API costs and usage
Third-Party Services:
- This project integrates with Piper TTS (local processing) and macOS Say (system built-in)
- We are not affiliated with, endorsed by, or officially connected to Anthropic, Apple, or Claude
- Piper TTS is subject to its terms of service
Privacy & Data:
- Piper TTS: All processing happens locally on your machine, no external data transmission
- macOS Say: All processing happens locally using Apple's built-in speech synthesis
Software License:
- Provided "as-is" under Apache 2.0 License without warranty of any kind
- See LICENSE file for full terms
- No liability for data loss, bugs, service interruptions, or any damages
Use at Your Own Risk:
- This is open-source software maintained by the community
- Always test in development before production use
- Monitor your API usage and costs regularly
---
Built with ❤️ by Paul Preibisch
- 🐦 Twitter: @997Fire
- 💼 LinkedIn: paul-preibisch
- 🌐 GitHub: paulpreibisch
Powered by:
- Piper TTS - Free neural voices
- Claude Code - AI coding assistant
- Licensed under Apache 2.0
Special Thanks:
- 💡 Claude Code Hooks Mastery by @disler - Hooks inspiration
- 🤖 BMAD METHOD - Multi-agent framework with auto voice switching integration
---
If AgentVibes makes your coding more fun:
- ⭐ Star this repo on GitHub
- 🐦 Tweet and tag @997Fire
- 🎥 Share videos of Claude with personality
- 💬 Tell dev friends about voice-powered AI
---
Ready to give Claude a voice? Install now and code with personality! 🎤✨