agentvibes 2.4.3 → 2.5.0

package/RELEASE_NOTES_v2.4.0_DRAFT.md

@@ -0,0 +1,116 @@
+# Release v2.4.0 - macOS Piper TTS Support (2025-01-15)
+
+## 🤖 AI Summary
+
+This minor release brings **full Piper TTS support to macOS** via precompiled binaries, eliminating the Python dependency conflicts that previously prevented macOS users from using free offline TTS. Mac users can now install Piper TTS with zero Python dependencies - just download and run! The installer automatically detects your Mac architecture (Intel or Apple Silicon) and downloads the appropriate binary. This release also includes comprehensive GitHub Actions CI testing to validate Piper installation across all macOS versions (13, 14, 15) and both architectures.
+
+## 📋 Changes
+
+### ✨ New Features
+- **macOS Piper TTS Support via Precompiled Binaries**
+  - Downloads official Piper binaries from rhasspy/piper releases
+  - Automatic architecture detection (Apple Silicon M1/M2/M3 vs Intel)
+  - Installs to `~/.local/bin/piper` with no Python dependencies
+  - Zero pipx or pip conflicts - pure binary installation
+  - Supports both `arm64` (Apple Silicon) and `x86_64` (Intel) architectures
+
+- **Comprehensive macOS CI Testing**
+  - Tests Piper binary installation on macOS 13, 14, and 15
+  - Tests user-reported `--no-deps` pip workaround method
+  - Validates both Intel and Apple Silicon architectures
+  - Confirms standard pipx failure and binary success
+  - Runs across 9 macOS configurations (3 OS × 3 Node versions)
+
+### 🐛 Bug Fixes
+- **Fixed macOS Piper Installation Failures**
+  - Resolved pipx dependency conflict issues reported by users
+  - Removed incorrect platform restriction blocking macOS
+  - Fixed "Piper TTS is only supported on WSL and Linux" error
+
+### 📚 Documentation
+- **Updated Provider Documentation**
+  - Corrected platform support matrix to include macOS
+  - Added macOS-specific installation requirements
+  - Clarified binary vs pipx installation methods
+  - Updated "Choose Piper TTS if" section with macOS callout
+
+- **Installer Script Documentation**
+  - Added platform detection logic documentation
+  - Documented binary download and extraction process
+  - Added PATH setup instructions for macOS users
+
+### 🔧 Maintenance
+- **Refactored Release Process**
+  - Extracted `showReleaseInfo()` function for code reuse
+  - Added critical ordering warning to `/release` command
+  - Documented README update before npm publish requirement
+
+## 🎯 User Impact
+
+**For macOS Users**: You can now use **completely free offline Piper TTS** on your Mac! No more ElevenLabs API key required. No more Python/pipx dependency hell. Just run `.claude/hooks/piper-installer.sh` and you're done. Works on both Intel Macs and Apple Silicon (M1/M2/M3).
+
+**For All Users**: The updated documentation now correctly reflects that Piper TTS works on **ALL platforms**: Windows, macOS, Linux, and WSL.
+
+**Installation is Simple**:
+```bash
+# Run AgentVibes installer
+npx agentvibes install --yes
+
+# Or directly run Piper installer
+.claude/hooks/piper-installer.sh
+
+# Add to PATH (if needed)
+echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+**Architecture Support**:
+- ✅ Apple Silicon (M1/M2/M3): Downloads `piper_macos_aarch64.tar.gz`
+- ✅ Intel Mac (x86_64): Downloads `piper_macos_x64.tar.gz`
+
+## 📦 Files Changed
+
+### Modified
+- `.claude/hooks/piper-installer.sh` - Added macOS binary installation support
+- `.github/workflows/test-macos.yml` - Added comprehensive Piper installation tests
+- `docs/providers.md` - Updated macOS support documentation
+- `.claude/commands/release.md` - Added README update ordering warning
+- `src/installer.js` - Refactored release info display
+
+### Statistics
+- 5 files changed
+- 241 insertions(+)
+- 130 deletions(-)
+
+## 🔄 Breaking Changes
+
+None. This release is fully backward compatible. Linux/WSL users continue using pipx installation, macOS users now get binary installation.
+
+## 🚀 Upgrade Notes
+
+Simply run:
+```bash
+npx agentvibes@latest install --yes
+```
+
+Existing configurations are preserved. If you're on macOS and previously couldn't install Piper, it will work now!
+
+## 🙏 Credits
+
+Special thanks to:
+- **BMadCode** for reporting the macOS installation issue
+- **rhasspy/piper** project for providing macOS binaries
+- Community members who suggested the `--no-deps` workaround
+
+## 📊 Testing
+
+This release includes extensive CI testing:
+- ✅ 9 macOS configurations (macOS 13/14/15 × Node 18/20/22)
+- ✅ Both architecture types (Intel and Apple Silicon)
+- ✅ Binary download and extraction validation
+- ✅ Piper execution tests
+- ✅ Fallback to pipx testing (confirms original issue)
+
+---
+
+**Full Changelog**: https://github.com/paulpreibisch/AgentVibes/compare/v2.3.1...v2.4.0

package/RELEASE_NOTES_v2.4.1_DRAFT.md

@@ -0,0 +1,61 @@
+# Release v2.4.1 - macOS Audio Playback Fix (2025-01-15)
+
+## 🤖 AI Summary
+
+This patch release fixes a critical audio playback issue on macOS where Piper TTS audio files were being created but not playing. The fix adds platform detection to use the native macOS `afplay` audio player instead of trying to use Linux-only audio players (mpv/aplay/paplay) that don't exist on macOS.
+
+## 📋 Changes
+
+### 🐛 Bug Fixes
+- **Fixed macOS Audio Playback in Piper TTS**
+  - Added platform detection to use `afplay` on macOS (Darwin)
+  - Keeps existing Linux audio players (mpv/aplay/paplay) for WSL/Linux
+  - Audio files now play correctly on macOS instead of silently failing
+  - File: `.claude/hooks/play-tts-piper.sh` line 329-339
+
+## 🎯 User Impact
+
+**For macOS Users**: Audio playback now works! If you were seeing "🎵 Saved to:" messages but hearing no sound, this update fixes that. Simply run `npx agentvibes@latest install --yes` to get the fix.
+
+**What Was Broken**: After v2.4.0 added macOS Piper TTS support, audio files were being generated successfully but the playback failed silently because the script was trying to use Linux audio players that don't exist on macOS.
+
+**What's Fixed**: The script now detects macOS and uses the native `afplay` command for audio playback.
+
+## 📦 Files Changed
+
+### Modified
+- `.claude/hooks/play-tts-piper.sh` - Added macOS platform detection for audio playback
+
+### Statistics
+- 1 file changed
+- 10 insertions(+)
+- 2 deletions(-)
+
+## 🔄 Breaking Changes
+
+None. This is a pure bug fix release.
+
+## 🚀 Upgrade Notes
+
+Simply run:
+```bash
+npx agentvibes@latest install --yes
+```
+
+This will update the hooks with the fixed audio playback script.
+
+## 🙏 Credits
+
+Special thanks to:
+- **BMadCode** for reporting the issue and testing on macOS! (Official AgentVibes contributor 🎉)
+- macOS users who helped identify the silent audio playback problem
+
+## 🔗 Related
+
+- v2.4.0 - Initial macOS Piper TTS support
+- Issue: Audio files created but not playing on macOS
+- Fix: Platform detection for native audio player selection
+
+---
+
+**Full Changelog**: https://github.com/paulpreibisch/AgentVibes/compare/v2.4.0...v2.4.1

package/RELEASE_NOTES_v2.5.0.md

@@ -0,0 +1,233 @@
+# Release v2.5.0 - Verbosity Control System
+
+**Release Date:** November 16, 2025
+**Type:** Minor Release (New Features)
+
+---
+
+## 🎙️ AI Summary
+
+**AgentVibes v2.5.0 introduces intelligent verbosity control** - giving you precise control over how much Claude speaks while working. This release adds a groundbreaking three-level system (LOW/MEDIUM/HIGH) that uses emoji markers (💭 🤔 ✓) for automatic TTS detection, eliminating the need for manual Bash calls. Whether you want minimal interruption during focused work or maximum transparency for learning and debugging, you can now adjust Claude's chattiness to match your workflow. Available via slash commands (`/agent-vibes:verbosity`) and MCP tools, with automatic protocol injection and real-time marker detection.
+
+---
+
+## ✨ New Features
+
+### 🎙️ Verbosity Control System (Issue #32)
+
+**Three intelligent verbosity levels:**
+
+**🔇 LOW (Minimal)** - Default behavior
+- Speaks only acknowledgments (task start) and completions (task end)
+- Quiet, focused work sessions
+- No intermediate reasoning spoken
+
+**🤔 MEDIUM (Balanced)**
+- Acknowledgments + completions
+- Major decisions: "I'll use grep to search"
+- Key findings: "Found 12 instances at line 1323"
+- Perfect for understanding major decisions without full narration
+
+**💭 HIGH (Maximum Transparency)**
+- 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, full transparency
+
+**How it works:**
+1. User sets verbosity level via slash command or MCP
+2. Session-start hook injects verbosity-aware protocol
+3. Claude uses emoji markers naturally in text (💭 🤔 ✓)
+4. Output hook auto-detects markers and triggers TTS
+5. No manual Bash TTS calls needed - all automatic!
+
+**New Files:**
+- `.claude/hooks/verbosity-manager.sh` (172 lines) - Get/set verbosity level
+- `.claude/hooks/user-prompt-output.sh` (111 lines) - Auto-detect emoji markers
+- `.claude/commands/agent-vibes/verbosity.md` (89 lines) - Slash command docs
+
+**Modified Files:**
+- `.claude/hooks/session-start-tts.sh` (+69 lines) - Inject verbosity protocol
+- `mcp-server/server.py` (+70 lines) - Add MCP tools
+- `README.md` (+47 lines) - Document verbosity feature
+
+**User Controls:**
+
+Slash Command:
+```bash
+/agent-vibes:verbosity           # Show current level
+/agent-vibes:verbosity high      # Maximum transparency
+/agent-vibes:verbosity medium    # Balanced
+/agent-vibes:verbosity low       # Minimal
+```
+
+MCP Tools:
+```python
+mcp__agentvibes__get_verbosity()
+mcp__agentvibes__set_verbosity(level="high")
+```
+
+---
+
+## 📊 Statistics
+
+- **Commits:** 2
+- **Files Changed:** 7
+- **Lines Added:** 558
+- **Lines Removed:** 2
+- **Net Change:** +556 lines
+
+**Files Modified:**
+- `.claude/commands/agent-vibes/verbosity.md` (+89 lines)
+- `.claude/hooks/session-start-tts.sh` (+69 lines)
+- `.claude/hooks/user-prompt-output.sh` (+111 lines)
+- `.claude/hooks/verbosity-manager.sh` (+172 lines)
+- `README.md` (+47 lines)
+- `mcp-server/server.py` (+70 lines)
+- `package.json` (version bump)
+
+---
+
+## 🎯 User Impact
+
+### Who Benefits?
+
+**Developers who want quiet focus:**
+- Set verbosity to LOW for minimal interruption
+- Only hear task start/end confirmations
+- Perfect for deep concentration work
+
+**Users learning Claude Code:**
+- Set verbosity to HIGH for full transparency
+- Hear Claude's complete thought process
+- Understand how AI reasons through problems
+
+**Power users who want balance:**
+- Set verbosity to MEDIUM for key insights
+- Hear major decisions and findings
+- Stay informed without overwhelming narration
+
+### Migration Notes
+
+**No breaking changes!**
+- Default verbosity is LOW (current behavior)
+- Existing installations continue working as before
+- Opt-in feature - activate when ready
+
+**To enable:**
+```bash
+/agent-vibes:verbosity high
+# Then restart Claude Code session
+```
+
+---
+
+## 🔧 Technical Details
+
+### Architecture
+
+**Emoji Marker System:**
+- 💭 = Reasoning/thinking (HIGH only)
+- 🤔 = Decisions (MEDIUM + HIGH)
+- ✓ = Findings/results (MEDIUM + HIGH)
+
+**Output Hook Processing:**
+- Intercepts Claude's text output
+- Regex pattern matching for emoji markers
+- Async TTS trigger (non-blocking)
+- Verbosity-aware filtering
+
+**Protocol Injection:**
+- Session-start hook reads verbosity level
+- Injects appropriate instructions for Claude
+- Different markers for each verbosity level
+- Automatic, transparent to user
+
+### Testing Performed
+
+✅ All three verbosity levels tested
+✅ Session-start hook protocol injection verified
+✅ MCP tools functional (get/set operations)
+✅ Verbosity manager script validation
+✅ Emoji marker auto-detection working
+✅ Documentation complete
+
+---
+
+## 🚀 Installation
+
+### New Installations
+```bash
+npx agentvibes@latest
+```
+
+### Existing Installations
+```bash
+npx agentvibes update
+```
+
+### Beta Testing
+```bash
+npx agentvibes@beta  # v2.5.0-beta.1 was available for testing
+```
+
+---
+
+## 📚 Documentation
+
+**Updated:**
+- `README.md` - New Verbosity Control section in Table of Contents
+- `.claude/commands/agent-vibes/verbosity.md` - Complete slash command guide
+- `mcp-server/server.py` - MCP tool documentation
+
+**New Sections:**
+- Verbosity Control in Key Features
+- Three-level system explanation
+- Usage examples for each level
+- MCP integration guide
+
+---
+
+## 🙏 Credits
+
+**Implementation:** Paul Preibisch ([@997Fire](https://x.com/997Fire))
+**Co-authored by:** Claude AI
+**Issue:** [#32](https://github.com/paulpreibisch/AgentVibes/issues/32)
+**Beta Release:** v2.5.0-beta.1 (Nov 16, 2025)
+
+---
+
+## 🔗 Links
+
+- **NPM Package:** https://www.npmjs.com/package/agentvibes
+- **GitHub Repository:** https://github.com/paulpreibisch/AgentVibes
+- **Issue #32:** https://github.com/paulpreibisch/AgentVibes/issues/32
+- **Documentation:** https://agentvibes.org
+
+---
+
+## Example: HIGH Verbosity in Action
+
+```
+User: "Find all TODO comments in the codebase"
+
+[TTS: "I'll search through the codebase"]
+💭 Let me use the Grep tool to search for TODO comments
+🤔 I'll search all files with pattern "TODO"
+[Grep runs...]
+✓ Found 12 TODO comments across 5 files
+💭 Let me organize these by file
+[TTS: "Found 12 TODO comments in 5 files"]
+```
+
+**What gets spoken automatically:**
+1. "Let me use the Grep tool to search for TODO comments"
+2. "I'll search all files with pattern TODO"
+3. "Found 12 TODO comments across 5 files"
+4. "Let me organize these by file"
+
+**No manual Bash TTS calls needed** - emoji markers trigger everything automatically! 🎉
+
+---
+
+**Full Changelog:** https://github.com/paulpreibisch/AgentVibes/compare/v2.4.3...v2.5.0

package/docs/macos-piper-issue.md

@@ -0,0 +1,172 @@
+# macOS Piper TTS Installation Issue
+
+## Problem
+
+User `BMadCode` on macOS reported installation failure when trying to use Piper TTS:
+
+### Error 1: Installer blocks macOS
+```bash
+➜ .claude/hooks/piper-installer.sh
+🎤 Piper TTS Installer
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+❌ Piper TTS is only supported on WSL and Linux
+   Your platform: Darwin
+
+   For macOS/Windows, use ElevenLabs instead:
+   /agent-vibes:provider switch elevenlabs
+```
+
+### Error 2: Direct pipx installation fails
+```bash
+➜ pipx install piper-tts
+
+Fatal error from pip prevented installation. Full pip output in file:
+    /Users/brianmadison/.local/pipx/logs/cmd_2025-11-15_09.14.02_pip_errors.log
+
+pip seemed to fail to build package:
+    piper-tts
+
+Some possibly relevant errors from pip install:
+    ERROR: Cannot install piper-tts==1.1.0, piper-tts==1.2.0 and piper-tts==1.3.0 because these package versions have conflicting dependencies.
+    ERROR: ResolutionImpossible: for help visit https://pip.pypa.io/en/latest/topics/dependency-resolution/#dealing-with-dependency-conflicts
+```
+
+## Root Cause Analysis
+
+### Documentation Inconsistency
+**File: `docs/providers.md`** (lines 32 and 90) claims:
+- "Cross-platform support (Windows, macOS, Linux)"
+- Platform Support: "Windows, macOS, Linux, WSL"
+
+**File: `.claude/hooks/piper-installer.sh`** (lines 50-56) explicitly blocks macOS:
+```bash
+# Check if running on WSL or Linux
+if ! grep -qi microsoft /proc/version 2>/dev/null && [[ "$(uname -s)" != "Linux" ]]; then
+  echo "❌ Piper TTS is only supported on WSL and Linux"
+  echo "   Your platform: $(uname -s)"
+  exit 1
+fi
+```
+
+### Why Piper Installation Fails on macOS
+
+1. **piper-tts PyPI package has dependency conflicts** - The `piper-tts` package on PyPI (versions 1.1.0-1.3.0) has unresolved dependency conflicts that prevent installation on macOS
+
+2. **Installer intentionally blocks macOS** - The script checks for Linux/WSL and rejects Darwin (macOS)
+
+3. **README says bash 5.x required** - README.md (lines 140-146) states macOS users need to install bash 5.x via Homebrew, but this is for AgentVibes hooks, not Piper itself
+
+## Solutions
+
+### Recommended Solution: Use ElevenLabs on macOS
+The installer's guidance is correct - macOS users should use **ElevenLabs** instead of Piper TTS:
+
+```bash
+# Switch to ElevenLabs provider
+/agent-vibes:provider switch elevenlabs
+
+# Set your API key
+export ELEVENLABS_API_KEY="your_key_here"
+```
+
+**Why?**
+- ✅ Works perfectly on macOS
+- ✅ No dependency conflicts
+- ✅ 150+ professional voices
+- ✅ Free tier: 10,000 chars/month
+- ✅ Get API key at https://elevenlabs.io
+
+### Alternative: Piper Binary (If Available)
+If Piper precompiled binaries for macOS exist, users could:
+1. Download macOS Piper binary
+2. Install manually to PATH
+3. Skip the Python/pipx installation
+
+**Note:** This requires Piper project to provide macOS binaries.
+
+## Proposed Fixes
+
+### Fix 1: Update Documentation (Priority: HIGH)
+Update `docs/providers.md` to reflect accurate platform support:
+
+**Current (incorrect):**
+```markdown
+| **Platform Support** | All platforms | Windows, macOS, Linux, WSL |
+```
+
+**Should be:**
+```markdown
+| **Platform Support** | All platforms | Windows, Linux, WSL |
+```
+
+**And add note:**
+```markdown
+**Note:** Piper TTS is not currently supported on macOS due to Python dependency conflicts.
+macOS users should use ElevenLabs instead.
+```
+
+### Fix 2: Update Troubleshooting Guide (Priority: MEDIUM)
+Add to `docs/troubleshooting.md`:
+
+```markdown
+## Piper TTS Installation Fails on macOS
+
+**Symptom:** `pipx install piper-tts` fails with dependency conflicts
+
+**Solution:** macOS is not currently supported for Piper TTS. Use ElevenLabs instead:
+
+1. Switch provider: `/agent-vibes:provider switch elevenlabs`
+2. Get API key: https://elevenlabs.io (free tier available)
+3. Set key: `export ELEVENLABS_API_KEY="your_key"`
+4. Test: `/agent-vibes:sample Aria`
+```
+
+### Fix 3: Improve Installer Error Message (Priority: LOW)
+Update `.claude/hooks/piper-installer.sh` error message to be more helpful:
+
+**Current:**
+```bash
+echo "❌ Piper TTS is only supported on WSL and Linux"
+echo "   Your platform: $(uname -s)"
+echo ""
+echo "   For macOS/Windows, use ElevenLabs instead:"
+echo "   /agent-vibes:provider switch elevenlabs"
+```
+
+**Improved:**
+```bash
+echo "❌ Piper TTS is not supported on macOS"
+echo "   Your platform: $(uname -s)"
+echo ""
+echo "   🎤 Recommended: Use ElevenLabs (150+ voices, free tier available)"
+echo "   1. Get API key: https://elevenlabs.io"
+echo "   2. Set key: export ELEVENLABS_API_KEY=\"your_key\""
+echo "   3. Switch provider: /agent-vibes:provider switch elevenlabs"
+echo ""
+echo "   Free tier: 10,000 chars/month"
+```
+
+## Testing Checklist
+
+- [ ] Update `docs/providers.md` platform support table
+- [ ] Add macOS note to Piper TTS section in `docs/providers.md`
+- [ ] Add macOS troubleshooting entry to `docs/troubleshooting.md`
+- [ ] Improve error message in `.claude/hooks/piper-installer.sh`
+- [ ] Verify ElevenLabs works correctly on macOS
+- [ ] Update README.md if needed
+- [ ] Test installer on macOS to confirm helpful error messages
+
+## References
+
+- User report: BMadCode via Discord/Slack (2025-11-15)
+- Piper TTS GitHub: https://github.com/rhasspy/piper
+- ElevenLabs: https://elevenlabs.io
+- Related: README.md bash 5.x requirement (lines 140-146)
+
+## Labels
+- `bug` - Documentation bug
+- `macos` - Platform-specific issue
+- `piper-tts` - Provider-specific
+- `documentation` - Needs doc updates
+- `good first issue` - Clear, well-defined fix