mbailey/voicemode

> Natural voice conversations with Claude Code (and other MCP capable agents)
VoiceMode enables natural voice conversations with Claude Code. Voice isn't about replacing typing - it's about being available when typing isn't.
**Perfect for:**
- Walking to your next meeting
- Cooking while debugging
- Giving your eyes a break after hours of screen time
- Holding a coffee (or a dog)
- Any moment when your hands or eyes are busy
See It In Action
Quick Start
**Requirements:** Computer with microphone and speakers
Option 1: Claude Code Plugin (Recommended)
The fastest way for Claude Code users to get started:
Option 2: Python installer package
Installs dependencies and the VoiceMode Python package.
For manual setup, see the Getting Started Guide.
Features
- **Natural conversations** - speak naturally, hear responses immediately
- **Works offline** - optional local voice services (Whisper STT, Kokoro TTS)
- **Low latency** - fast enough to feel like a real conversation
- **Smart silence detection** - stops recording when you stop speaking
- **Privacy options** - run entirely locally or use cloud services
Compatibility
**Platforms:** Linux, macOS, Windows (native or WSL), NixOS
**Python:** 3.10-3.14
Configuration
VoiceMode works out of the box. For customization:
See the Configuration Guide for all options.
Permissions Setup (Optional)
To use VoiceMode without permission prompts, add to ~/.claude/settings.json:
See the Permissions Guide for more options.
Local Voice Services
For privacy or offline use, install local speech services:
- **Whisper.cpp** - Local speech-to-text
- **Kokoro** - Local text-to-speech with multiple voices
These provide the same API as OpenAI, so VoiceMode switches seamlessly between them.
Installation Details
System Dependencies by Platform
Ubuntu/Debian
**WSL2 users**: The pulseaudio packages above are required for microphone access.
Fedora/RHEL
macOS
NixOS
Alternative Installation Methods
From source
NixOS system-wide
Troubleshooting
| Problem | Solution |
|---------|----------|
| No microphone access | Check terminal/app permissions. WSL2 needs pulseaudio packages. |
| UV not found | Run curl -LsSf https://astral.sh/uv/install.sh \| sh |
| OpenAI API error | Verify OPENAI_API_KEY is set correctly |
| No audio output | Check system audio settings and available devices |
Save Audio for Debugging