Squadron Comms Plugin
Voice communication system with ElevenLabs TTS for multi-agent coordination in Claude Code
A Claude Code plugin that enables voice broadcasting for coordinated multi-agent operations. Spawn colored squadron agents (Red, Gold, Blue, Green) that announce their progress using distinct ElevenLabs voices while working on tasks in parallel.
Features
-
🎯 Four Specialized Squadron Agents: Each with unique voice profiles and mission focuses
- Red Squadron (Daniel, British) - General purpose tasks
- Gold Squadron (Joseph, British) - Analysis and research
- Blue Squadron (Jeremy, American-Irish) - Performance and optimization
- Green Squadron (Matilda, American) - Polish and UX improvements
-
🎙️ Voice Broadcasting: Real-time TTS announcements using ElevenLabs
-
📝 Mission Logging: All broadcasts logged to JSONL for history
-
🔒 Concurrent Safe: File locking prevents audio overlap
-
🎨 Color-Coded: Visual squadron identification in Claude Code
-
📡 Commander Role: Main agent can coordinate squadrons
How It Works
The Squadron Comms Plugin uses a two-component audio architecture:
-
TTS Generation (ElevenLabs): The ElevenLabs MCP server generates speech audio from text
- Converts messages to MP3 files with squadron-specific voices
- Handles voice synthesis, speed adjustment, and audio encoding
-
Audio Playback (sounddevice + PortAudio): Python sounddevice library plays the generated audio
- Cross-platform audio playback via PortAudio
- File locking prevents simultaneous broadcasts from overlapping
- Automatic mission logging to JSONL format
The complete broadcast flow:
Text → ElevenLabs TTS → MP3 file → broadcast.py → play_with_lock.py → Audio output + Log entry
This hybrid approach provides the best of both worlds: high-quality ElevenLabs voices with reliable cross-platform playback.
Quick Start
1. Prerequisites
- Claude Code CLI installed
- ElevenLabs API key (get one here)
- PortAudio library (for audio playback)
Install PortAudio:
macOS
PortAudio usually installs automatically when the ElevenLabs MCP server is installed. If you encounter audio playback issues:
brew install portaudio
Verify installation:
brew list portaudio
Linux (Ubuntu/Debian)
Install PortAudio library:
sudo apt-get update
sudo apt-get install libportaudio2
For development headers (if needed):
sudo apt-get install portaudio19-dev
Verify installation:
dpkg -l | grep libportaudio2
Linux (Fedora/RHEL)
Install PortAudio library:
sudo dnf install portaudio
Verify installation:
rpm -qa | grep portaudio
Windows
PortAudio usually installs automatically when the ElevenLabs MCP server is installed via uvx elevenlabs-mcp.
If you encounter "PortAudio library not found" errors:
- Ensure Python is installed from python.org
- Reinstall audio packages:
pip install --force-reinstall sounddevice soundfile - Restart Claude Code
Note: On Windows, PortAudio typically installs automatically as part of the sounddevice package dependencies. Manual installation is rarely needed.
2. Installation
Option A: From Marketplace (Recommended)
# Add the 1Shot Labs marketplace
/plugin marketplace add 1Shot-Labs/marketplace
# Install the plugin
/plugin install squadron-comms
Option B: Local Development
# Clone the repository
git clone https://github.com/1Shot-Labs/squadron-comms-plugin.git
# Load the plugin
claude --plugin-dir ./squadron-comms-plugin
3. Configure ElevenLabs API Key
Set your ElevenLabs API key as an environment variable:
macOS / Linux
Temporary (current session only):
export ELEVENLABS_API_KEY="your_api_key_here"
Permanent:
Add to your shell configuration file:
# For bash
echo 'export ELEVENLABS_API_KEY="your_api_key_here"' >> ~/.bashrc
source ~/.bashrc
# For zsh
echo 'export ELEVENLABS_API_KEY="your_api_key_here"' >> ~/.zshrc
source ~/.zshrc
Verify it's set:
echo $ELEVENLABS_API_KEY