agentvibes 4.0.1 → 4.2.0

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**: v4.0.0
+**Author**: Paul Preibisch ([@997Fire](https://x.com/997Fire)) | **Version**: v4.2
 
 ---
 
@@ -40,36 +40,94 @@ Whether you're coding in Claude Code, chatting in Claude Desktop, using Warp Ter
 
 ---
 
-## 🌟 NEW FEATURE HIGHLIGHTS
+## 🌟 NEW IN v4.2 — BMAD Voices, SSH Receiver & More
 
-### 🖥️ AgentVibes v4.0 Interactive TUI Console
+### 🎭 BMAD Party Mode — Every Agent Has Its Own Voice
 
-![AgentVibes TUI Console](docs/installation-screenshots/screenshot-voices.png)
+The BMad Method (Build More Architect Dreams) is an AI-driven development framework that helps you build software from ideation through agentic implementation with specialized AI agents, guided workflows, and intelligent planning that adapts to your project's complexity.
 
-**🎤 Browse, Sample & Install 914 Voices — All From One Console**
+**Every BMAD agent now speaks with their own unique voice, music, and personality.**
+
+When party mode runs a multi-agent discussion, the Architect, PM, Developer, QA, and Analyst each sound completely different — making every role immediately recognizable.
+
+**Auto-enabled** — if BMAD is installed, party mode activates automatically. Open the BMad Tab to configure each agent:
 
 ```bash
-npx agentvibes install
+npx agentvibes   # Press B to open the BMad Tab
 ```
 
-The new **AgentVibes TUI Console** is a full interactive terminal application with tabbed navigation:
+**Per-agent configuration:**
+- 🎙️ **Voice** — 914 voices to choose from, auto-assigned gender-aware
+- 🎵 **Background Music** — Unique ambient track per agent (cinematic, lo-fi, jazz...)
+- 🎚️ **Music Volume** — Per-agent level, or set all at once via Bulk Edit
+- 🎛️ **Reverb** — none / room / hall / cathedral / studio per agent
+- 💬 **Pretext** — Custom intro phrase ("Winston says:..." before every line)
+- 🎭 **Personality** — sarcastic, dramatic, pirate, cheerful, and more
+- 🔇 **No Overlap** — Speech lock ensures agents never talk over each other
+- ✨ **Markdown-Clean** — Asterisks and formatting stripped before TTS
 
-- 🖥️ **Settings Tab** - Real-time settings management with live preview
-- 🎤 **Voices Tab** - Browse, sample, and install 914+ voices with one keypress
-- 🎵 **Music Tab** - Browse and preview 16 background music tracks
-- ❓ **Help Tab** - Built-in documentation and quick reference
+### 🎛️ BMad Tab — Visual Agent Configurator
 
-**914 Total Voices:**
-- 904 High-Quality Piper TTS Speakers (libritts-high model)
-- 10 Hand-Curated Personality Voices
+The `npx agentvibes` TUI now includes a full **BMad Tab** for managing every agent visually — inspired by the Voices tab, with the same columns and navigation polish:
 
-**Perfect for:**
-- Managing all AgentVibes settings in one place
-- Finding your ideal AI voice
-- Quick voice switching with Save Locally/Globally options
-- Browsing and previewing background music
+```bash
+npx agentvibes   # Press B for BMad Tab
+```
+
+| Agent | Voice | Gender | Provider | Reverb | Music | Vol | Pretext |
+|-------|-------|--------|----------|--------|-------|-----|---------|
+| 🏢 Winston | Rose Ibex | Female | Piper (LibriTTS) | studio | jazz | 65% | Winston says |
+| 🧠 Larry | Kusal | Male | Piper | hall | cinematic | 80% | Larry says |
+
+**Highlights:**
+- **Beautified voice names** — `16Speakers::Rose_Ibex` shows as `Rose Ibex`; `en_US-kusal-medium` shows as `Kusal`
+- **Gender & Provider columns** — see voice metadata at a glance, just like the Voices tab
+- **Inline row hints** — navigate to any agent and see `[Space] Preview  [Enter] Configure` on the row itself
+- **Preview spinner** — animated `⠋⠙⠹⠸` braille spinner while audio plays
+
+| Key | Action |
+|-----|--------|
+| `↑↓` / `jk` | Navigate agents |
+| `Space` | Preview agent (spinner shows while playing) |
+| `Enter` | Configure voice, music, volume, reverb, personality, pretext |
+| `A` | Auto-assign unique voices (gender-aware, no repeats) |
+| `B` | Bulk Edit — set music / volume / pretext / reverb for all agents |
+| `X` | Reset agent to defaults |
+
+---
+
+### 🖥️ SSH Receiver — Hear Your Headless Server
+
+**Run Claude on a cloud box and hear the TTS on your local machine.**
 
-Launch now: `npx agentvibes`
+The new **Receiver Tab** streams TTS audio from voiceless remote servers to your local machine over TCP — perfect for AWS/GCP dev boxes, WSL2, and SSH sessions.
+
+```bash
+# On your local machine — open TUI, go to Receiver tab, click Start
+npx agentvibes
+
+# On the remote server — AgentVibes auto-detects the receiver and streams
+```
+
+Zero-config forwarding. Works with Piper, macOS Say, and Soprano.
+
+---
+
+### ⚡ TTS Latency -~1 Second
+
+- **Batched Node.js calls** — 6 separate profile reads collapsed into 1 (~900ms saved)
+- **inotifywait queue** — file-event-based worker, no polling delay
+- **Background cache cleanup** — off the critical path every 10th call
+
+---
+
+### 🎨 ANSI Banner Colors + Toggle
+
+Full color in the TTS banner (gold voice, cyan reverb, traffic-light cache). Hide it without muting:
+
+```bash
+touch ~/.agentvibes/banner-disabled   # or say "turn off the TTS banner"
+```
 
 ---
 
@@ -77,8 +135,10 @@ Launch now: `npx agentvibes`
 
 **Add custom prefixes to every TTS announcement!**
 
+Configure via the AgentVibes TUI Settings tab:
+
 ```bash
-npx agentvibes config intro-text
+npx agentvibes   # Navigate to Settings tab
 ```
 
 Transform generic AI responses into your personal brand:
@@ -112,7 +172,7 @@ Transform generic AI responses into your personal brand:
 - `"CodeBot: "` - Development assistant
 - `"Chef AI: "` - Cooking helper
 
-Configure now: `npx agentvibes config intro-text`
+Configure via: `npx agentvibes` → Settings tab
 
 ---
 
@@ -120,11 +180,13 @@ Configure now: `npx agentvibes config intro-text`
 
 **Upload your own background music with battle-tested security!**
 
+Configure via the AgentVibes TUI Music tab:
+
 ```bash
-npx agentvibes config music
+npx agentvibes   # Navigate to Music tab
 ```
 
-Replace the default background tracks with your own audio files for complete sonic branding.
+Replace the default background tracks with your own audio files.
 
 **Supported Formats:**
 - 🎵 MP3 (.mp3)
@@ -149,10 +211,10 @@ Replace the default background tracks with your own audio files for complete son
 - Duration warnings for non-optimal lengths
 
 **Perfect for:**
-- 🎸 **Team Audio Branding** - Company theme music
-- 🎮 **Gaming Sessions** - Epic background tracks
-- 🎼 **Personal Playlists** - Your favorite instrumental
-- 🎹 **Focus Music** - Lo-fi, classical, ambient
+- 🎮 **Making coding fun** - Your favorite beats while you build
+- 🎼 **Setting the mood** - Match the music to the task (lo-fi for debugging, epic for shipping)
+- 🗂️ **Identifying projects** - Different track per repo so you always know which project Claude is in
+- 🎹 **Deep focus** - Ambient or classical to stay in flow
 
 **Features:**
 - Preview before setting
@@ -168,7 +230,7 @@ Replace the default background tracks with your own audio files for complete son
 4. Enable/Disable - Toggle background music
 5. Preview current - Sample your music
 
-Configure now: `npx agentvibes config music`
+Configure via: `npx agentvibes` → Music tab
 
 **Security Certified:** See full audit report at `docs/security/SECURITY-AUDIT.md`
 
@@ -176,14 +238,22 @@ Configure now: `npx agentvibes config music`
 
 ### 🎯 Key Features
 
-**🌟 NEW IN v4.0.0 — Interactive Console & Voice Explorer:**
-- 🖥️ **Interactive TUI Console** - Full terminal UI with tabbed navigation (Settings, Voices, Music, Help)
-- 🎤 **914+ Voices** - Browse, preview, and install voices with multi-speaker support
-- 🔊 **Reliable TTS Hooks** - SessionStart JSON output + auto git-init for guaranteed hook support
+**🌟 NEW IN v4.2 — BMAD Party Mode & SSH Receiver:**
+- 🎭 **BMAD Party Mode Voices** — Each agent speaks with their unique voice, music, reverb, personality
+- 🖥️ **SSH Receiver Tab** — Stream TTS audio from headless servers to your local machine over TCP
+- 🎛️ **BMad Tab (TUI)** — Visual agent configurator with auto-assign and bulk edit
+- ⚡ **TTS Latency -1s** — Batched Node.js calls, inotifywait queue, background cleanup
+- 🎨 **ANSI Banner Colors Restored** — Gold/cyan/traffic-light colors in TTS info banner
+- 🔕 **Banner Toggle** — Hide TTS banner without muting (`~/.agentvibes/banner-disabled`)
+- 🔇 **No Party Mode Overlap** — Agents wait for full audio before next speaks
+- 🧹 **Markdown-Clean Speech** — Asterisks/formatting stripped automatically from party mode
+
+**🌟 NEW IN v3.6.0 — Voice Explorer Release:**
 - 🏷️ **Friendly Voice Names** - "Ryan" instead of "en_US-libritts_r-medium-speaker-123"
 - 💬 **Intro Text (Pretext)** - Custom prefix for all TTS ("FireBot: Starting...")
 - 🎵 **Custom Background Music** - Upload your own audio files with battle-tested security
-- 🛡️ **Security Hardening** - 58 issues fixed, 180+ attack variations tested, OWASP compliant
+- 🎨 **Interactive Installer** - Preview voices and music during installation
+- 🛡️ **Security Hardening** - 180+ attack variations tested, 100% blocked, OWASP compliant
 
 **🪟 NEW IN v3.5.5 — Native Windows Support:**
 - 🖥️ **Windows Native TTS** - Soprano, Piper, and Windows SAPI providers. No WSL required!
@@ -243,10 +313,11 @@ All 50+ Piper voices AgentVibes provides are sourced from Hugging Face's open-so
 - [📋 Prerequisites](#-prerequisites) - What you actually need (Node.js + optional tools)
 - [✨ What is AgentVibes?](#-what-is-agentvibes) - Overview & key features
 - [🌟 NEW FEATURE HIGHLIGHTS](#-new-feature-highlights) - **START HERE!**
-  - [🖥️ TUI Console v4.0](#%EF%B8%8F-agentvibes-v40-interactive-tui-console) - Interactive settings, voices, music
+  - [🎭 BMAD Party Mode](#-bmad-party-mode--multi-agent-voice-conversations) - Per-agent voices, music, reverb
+  - [🖥️ SSH Receiver](#️-agentvibes-receiver--remote-audio-streaming) - Stream audio from headless servers
   - [💬 Intro Text](#-intro-text-pretext---your-personal-ai-branding) - Custom TTS prefixes
   - [🎵 Custom Background Music](#-custom-background-music---complete-audio-control) - Upload your own tracks
-- [📰 Latest Release](#-latest-release) - v4.0.0 "Interactive Console & Voice Explorer"
+- [📰 Latest Release](#-latest-release) - v4.2 "Party Mode" — BMAD multi-agent voices, SSH Receiver, BMad Tab, ~1s latency improvement
 - [🪟 Windows Setup Guide for Claude Desktop](mcp-server/WINDOWS_SETUP.md) - Complete Windows installation with WSL & Python
 
 ### AgentVibes MCP (Natural Language Control)
@@ -292,44 +363,81 @@ All 50+ Piper voices AgentVibes provides are sourced from Hugging Face's open-so
 
 ## 📰 Latest Release
 
-**[v4.0.0 - Interactive Console & Voice Explorer](https://github.com/paulpreibisch/AgentVibes/releases/tag/v4.0.0)** 🎉
+**[v4.2 - "Party Mode" Release](https://github.com/paulpreibisch/AgentVibes/releases/tag/v4.2)** 🎉
 
-AgentVibes v4.0.0 is a major release that transforms the user experience with a full interactive TUI console, 914+ voices in the built-in Voices tab, and comprehensive platform support including Windows, macOS, Android/Termux, and SSH remote audio.
+This is the biggest AgentVibes release since the TUI launched in v4.0. Two headline features: **BMAD Party Mode** gives every agent their own voice and music, and the **SSH Receiver** lets you hear your headless server speak on your local machine.
 
-### 🖥️ Interactive TUI Console
+### 🎭 BMAD Party Mode — Multi-Agent Voice Conversations
 
-**Full terminal UI with tabbed navigation and real-time settings!**
+The BMad Method (Build More Architect Dreams) is an AI-driven development framework module that helps you build software from ideation through agentic implementation with specialized AI agents, guided workflows, and intelligent planning.
 
-![AgentVibes Voices Tab](docs/installation-screenshots/screenshot-voices.png)
+Every agent in a BMAD discussion now speaks with their own individually configured voice, music, reverb, and personality — making the Architect, PM, Developer, QA, and Analyst immediately recognizable the moment they speak.
 
-![AgentVibes Music Tab](docs/installation-screenshots/screenshot-music.png)
+**Auto-enabled** — party mode activates automatically when BMAD is detected. Configure agents visually:
 
 ```bash
-npx agentvibes install
+npx agentvibes   # Press B for BMad Tab
 ```
 
-### ✨ Key Highlights
+**Each agent gets:**
+- 🎙️ **Their own voice** — 914 to choose from, or auto-assign gender-aware
+- 🎵 **Their own music track** — cinematic for the Architect, lo-fi for the Dev
+- 🎚️ **Their own volume** — fine-tune per-agent, or bulk-set all at once
+- 🎛️ **Their own reverb** — studio, hall, cathedral, room, or none
+- 💬 **Their own pretext** — "Winston says:..." before every line
+- 🎭 **Their own personality** — sarcastic, dramatic, pirate, cheerful...
+- 🔇 **No overlap** — agents wait for full audio before the next one speaks
+- ✨ **Markdown stripped** — no "asterisk asterisk" in TTS output
+
+### 🎛️ BMad Tab — Full Visual Agent Configurator
 
-- 🖥️ **Interactive TUI Console** - Full terminal UI with tabbed navigation (Settings, Voices, Music, Help)
-- 🎤 **914+ Voices** - Browse, preview, and install voices with multi-speaker support
-- 🔊 **Reliable TTS Hooks** - SessionStart JSON output + auto git-init for guaranteed hook support
-- 🪟 **Windows Support** - Native Soprano, Piper, and SAPI providers
-- 📱 **Android/Termux** - Mobile TTS with termux-ssh provider
-- 🎵 **Background Music** - Custom track uploads with secure validation
-- 🛡️ **Security Hardened** - 58 issues fixed, 180+ attack variations tested
+Manage every agent from an interactive table — same polish as the Voices tab:
+
+| Key | Action |
+|-----|--------|
+| `Space` | Preview agent with full profile (animated spinner while playing) |
+| `Enter` | Configure voice, music, volume, reverb, personality, pretext |
+| `A` | Auto-assign unique voices (gender-aware, no repeats) |
+| `B` | Bulk Edit — set music / volume / pretext / reverb for all agents |
+| `X` | Reset agent to defaults |
+
+The table shows **Voice, Gender, Provider, Reverb, Music, Vol, Pretext** columns. Voice names are automatically beautified: `16Speakers::Rose_Ibex` → `Rose Ibex`.
+
+### 🖥️ SSH Receiver — Hear Your Headless Server
+
+Stream TTS from a cloud box, WSL2, or any voiceless server directly to your local machine over TCP:
+
+```bash
+# Local: open TUI → Receiver tab → Start
+npx agentvibes
+
+# Remote: AgentVibes auto-detects the receiver and streams audio to you
+```
+
+### ⚡ ~1 Second Faster TTS
+
+- 6 Node.js profile reads collapsed into 1 (~900ms saved per speech)
+- `inotifywait` queue worker — no polling delay
+- Cache cleanup runs off the critical path
+
+### 🎨 ANSI Colors Restored + Banner Toggle
+
+Full color in the TTS banner. Silence it without muting audio:
+```bash
+touch ~/.agentvibes/banner-disabled   # or: "turn off the TTS banner" via MCP
+```
 
 ### Quick Install
 
 ```bash
-# Install AgentVibes
 npx agentvibes install
 ```
 
-💡 **Tip:** If `npx agentvibes` shows an older version, clear cache: `npm cache clean --force && npx agentvibes@latest --help`
+💡 **Tip:** If `npx agentvibes` shows an older version: `npm cache clean --force && npx agentvibes@latest`
 
-🐛 **Found a bug?** Report at [GitHub Issues](https://github.com/paulpreibisch/AgentVibes/issues)
+🐛 **Found a bug?** [GitHub Issues](https://github.com/paulpreibisch/AgentVibes/issues)
 
-[→ View Complete Release Notes](RELEASE_NOTES.md) | [→ View All Releases](https://github.com/paulpreibisch/AgentVibes/releases)
+[→ View Complete Release Notes](RELEASE_NOTES.md) | [→ View Previous Release (v4.0.1)](https://github.com/paulpreibisch/AgentVibes/releases/tag/v4.0.1) | [→ View All Releases](https://github.com/paulpreibisch/AgentVibes/releases)
 
 [↑ Back to top](#-table-of-contents)
 
@@ -391,7 +499,7 @@ AgentVibes includes a full **Text User Interface (TUI)** built with blessed.js f
 | `npx agentvibes install` | Open the Install tab directly |
 | `npx agentvibes config` | Open the Settings tab directly |
 
-Once inside, use **Tab** / **Shift+Tab** to switch between tabs: **Voices**, **Music**, **Settings**, and **Install**. Use **[** / **]** to page through voice and music catalogs.
+Once inside, use **Tab** / **Shift+Tab** to switch between tabs: **Voices**, **Music**, **BMad**, **Settings**, **Receiver**, and **Install**. Use **[** / **]** to page through voice and music catalogs.
 
 ---
 
@@ -407,6 +515,8 @@ macOS ships with bash 3.2 (from 2007). After this, everything works perfectly!
 
 [↑ Back to top](#-table-of-contents)
 
+[↑ Back to top](#-table-of-contents)
+
 ---
 
 ## 📋 Prerequisites - What You Actually Need
@@ -755,9 +865,8 @@ AgentVibes provides **50+ slash commands** and **natural language MCP equivalent
 ### Intro Text Commands
 
 ```bash
-# Configure intro text
-/agent-vibes:config intro-text
-npx agentvibes config intro-text
+# Configure intro text — open Settings tab
+npx agentvibes
 
 # View current intro text
 cat ~/.claude/config/intro-text.txt
@@ -773,16 +882,8 @@ cat ~/.claude/config/intro-text.txt
 ### Custom Music Commands
 
 ```bash
-# Configure background music
-/agent-vibes:config music
-npx agentvibes config music
-
-# Menu options:
-# 1. Change music - Upload new audio file
-# 2. Remove music - Clear custom music
-# 3. Reset to default - Restore built-in tracks
-# 4. Enable/Disable - Toggle background music
-# 5. Preview current - Sample current music
+# Configure background music — open Music tab
+npx agentvibes
 ```
 
 **MCP Equivalent:**
@@ -890,7 +991,7 @@ Every task acknowledgment plays **twice** - first in English, then in your targe
 
 ## 🗣️ Voice Library
 
-**NEW in v4.0.0:** Browse, sample, and install from 914+ voices directly in the interactive TUI console! Launch with `npx agentvibes`.
+Use the **AgentVibes TUI installer** (`/audio-browser`) to browse, sample, and install from 914 voices interactively.
 
 ### Friendly Voice Names
 
@@ -1754,19 +1855,19 @@ Both do the exact same thing - MCP is more convenient, slash commands are more t
 - **Optional**: sox (audio effects), ffmpeg (background music, padding)
 - All TTS generation works without optional dependencies - they just enhance the experience
 
-### TUI Console & New Features
+### Voice Features
 
 **Q: How do I browse and install voices?**
-**A:** Run `npx agentvibes` to open the interactive TUI console. Navigate to the Voices tab using Tab key, browse 914+ voices with arrow keys, press ENTER to sample, and select to install.
+**A:** Use the built-in TUI installer by running `/audio-browser` in Claude Code. Navigate with arrow keys, press ENTER to sample voices, and select one to install. AgentVibes switches to the chosen voice automatically.
 
 **Q: What are friendly voice names?**
 **A:** Instead of technical IDs like `en_US-ryan-high`, you can now use simple names like "Ryan" when switching voices. All 904+ voices have friendly names matched to their characteristics.
 
 **Q: How do I set up custom intro text?**
-**A:** During installation, you'll be prompted for intro text. You can also configure it anytime with `npx agentvibes config intro-text`. Enter text like "FireBot: " and it will prefix all TTS announcements.
+**A:** During installation you'll be prompted for intro text. You can also configure it anytime via `npx agentvibes` → Settings tab. Enter text like "FireBot: " and it will prefix all TTS announcements.
 
 **Q: Can I use my own background music?**
-**A:** Yes! Run `npx agentvibes config music` and select "Change music". Provide the path to your audio file (.mp3, .wav, .ogg, or .m4a). Files are validated for security and must be under 50MB.
+**A:** Yes! Run `npx agentvibes` and open the Music tab. Select "Change music" and provide the path to your audio file (.mp3, .wav, .ogg, or .m4a). Files are validated for security and must be under 50MB.
 
 **Q: What's the recommended duration for custom music?**
 **A:** Between 30-90 seconds is ideal for smooth looping. The system supports up to 300 seconds (5 minutes) but will warn you if the duration is non-optimal.
@@ -1774,14 +1875,11 @@ Both do the exact same thing - MCP is more convenient, slash commands are more t
 **Q: Are friendly voice names case-sensitive?**
 **A:** No! You can type "ryan", "Ryan", or "RYAN" - they all work. The voice resolution is case-insensitive.
 
-**Q: Can I favorite voices without installing them?**
-**A:** Yes! In the Voices tab, press 'F' to mark any voice as a favorite. Favorites are saved and you can filter to show only favorites later.
-
 **Q: Does custom music work with all TTS providers?**
 **A:** Yes! Custom background music works with Piper TTS, Soprano, macOS Say, and Windows SAPI.
 
 **Q: Can I preview music before setting it as my background?**
-**A:** Yes! When configuring custom music with `npx agentvibes config music`, you can select "Preview current" to hear your music. During installation, you can also sample all built-in tracks.
+**A:** Yes! In `npx agentvibes` → Music tab, select "Preview current" to hear your music. During installation, you can also sample all built-in tracks.
 
 **Q: What security measures protect custom music uploads?**
 **A:** AgentVibes implements **defense-in-depth security with 7 validation layers**, tested against 180+ attack variations: