https://github.com/mbailey/voicemode
Voice Mode for Claude Code
https://github.com/mbailey/voicemode
asr claudecode kokoro livekit mcp mcp-server tts voice whisper
Last synced: 2 months ago
JSON representation
Voice Mode for Claude Code
- Host: GitHub
- URL: https://github.com/mbailey/voicemode
- Owner: mbailey
- Created: 2025-06-08T16:16:19.000Z (10 months ago)
- Default Branch: master
- Last Pushed: 2025-06-19T17:23:13.000Z (10 months ago)
- Last Synced: 2025-06-19T17:46:31.908Z (10 months ago)
- Topics: asr, claudecode, kokoro, livekit, mcp, mcp-server, tts, voice, whisper
- Language: Python
- Homepage: https://getvoicemode.com/
- Size: 772 KB
- Stars: 16
- Watchers: 1
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
Awesome Lists containing this project
- awesome-mcp - mbailey/voicemode
- awesome-mcp-servers - voicemode - A complete voice interaction MCP server providing speech-to-text, text-to-speech, and real-time voice conversation capabilities for LLM-based assistants. ([Read more](/details/voicemode.md)) `speech-to-text` `text-to-speech` `audio` (Media Processing Mcp Servers)
- toolsdk-mcp-registry - ❌ voice-mcp - way voice conversations through multiple transport methods including local microphone recording and LiveKit room-based communication, with configurable STT/TTS services and automatic transport fallback for creating voice-enabled applications. (python) (Communication / How to Submit)
- best-of-mcp-servers - GitHub - 23% open · ⏱️ 07.03.2026) (Text-to-Speech)
- awesome-mcp-servers - **VoiceMode** - Enable voice conversations with Claude using any OpenAI-compatible STT/TTS service getvoicemode.com `http` `ai` `openai` `git` `github` (📦 Other)
- awesome-mcp - mbailey/voicemode - VoiceMode is a cross-platform tool that enables natural voice conversations with AI coding assistants like Claude Code through the Model Context Protocol (MCP), supporting local and cloud-based speech services for real-time interactive coding. (MCP Clients / IDE Extensions & Code Assistants)
- awesome-claude-code - VoiceMode MCP - VoiceMode MCP brings natural conversations to Claude Code. It supports any OpenAI API compatible voice services and installs free and open source voice services (Whisper.cpp and Kokoro-FastAPI). (Tooling 🧰 / General)
README
# VoiceMode
> Natural voice conversations with Claude Code (and other MCP capable agents)
[](https://pepy.tech/project/voice-mode)
[](https://pepy.tech/project/voice-mode)
[](https://pepy.tech/project/voice-mode)
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
[](https://www.youtube.com/watch?v=cYdwOD_-dQc)
## Quick Start
**Requirements:** Computer with microphone and speakers
### Option 1: Claude Code Plugin (Recommended)
The fastest way for Claude Code users to get started:
```bash
# Add the plugin marketplace
claude plugin marketplace add mbailey/plugins
# Install VoiceMode plugin
claude plugin install voicemode@mbailey
## Install dependencies (CLI, Local Voice Services)
/voicemode:install
# Start talking!
/voicemode:converse
```
### Option 2: Python installer package
Installs dependencies and the VoiceMode Python package.
```bash
# Install UV package manager (if needed)
curl -LsSf https://astral.sh/uv/install.sh | sh
# Run the installer (sets up dependencies and local voice services)
uvx voice-mode-install
# Add to Claude Code
claude mcp add --scope user voicemode -- uvx --refresh voice-mode
# Optional: Add OpenAI API key as fallback for local services
export OPENAI_API_KEY=your-openai-key
# Start a conversation
claude converse
```
For manual setup, see the [Getting Started Guide](docs/tutorials/getting-started.md).
## 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 (WSL), NixOS
**Python:** 3.10-3.14
## Configuration
VoiceMode works out of the box. For customization:
```bash
# Set OpenAI API key (if using cloud services)
export OPENAI_API_KEY="your-key"
# Or configure via file
voicemode config edit
```
See the [Configuration Guide](docs/guides/configuration.md) for all options.
## Local Voice Services
For privacy or offline use, install local speech services:
- **[Whisper.cpp](docs/guides/whisper-setup.md)** - Local speech-to-text
- **[Kokoro](docs/guides/kokoro-setup.md)** - 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
```bash
sudo apt update
sudo apt install -y ffmpeg gcc libasound2-dev libasound2-plugins libportaudio2 portaudio19-dev pulseaudio pulseaudio-utils python3-dev
```
**WSL2 users**: The pulseaudio packages above are required for microphone access.
#### Fedora/RHEL
```bash
sudo dnf install alsa-lib-devel ffmpeg gcc portaudio portaudio-devel python3-devel
```
#### macOS
```bash
brew install ffmpeg node portaudio
```
#### NixOS
```bash
# Use development shell
nix develop github:mbailey/voicemode
# Or install system-wide
nix profile install github:mbailey/voicemode
```
Alternative Installation Methods
#### From source
```bash
git clone https://github.com/mbailey/voicemode.git
cd voicemode
uv tool install -e .
```
#### NixOS system-wide
```nix
# In /etc/nixos/configuration.nix
environment.systemPackages = [
(builtins.getFlake "github:mbailey/voicemode").packages.${pkgs.system}.default
];
```
## 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
```bash
export VOICEMODE_SAVE_AUDIO=true
# Files saved to ~/.voicemode/audio/YYYY/MM/
```
## Documentation
- [Getting Started](docs/tutorials/getting-started.md) - Full setup guide
- [Configuration](docs/guides/configuration.md) - All environment variables
- [Whisper Setup](docs/guides/whisper-setup.md) - Local speech-to-text
- [Kokoro Setup](docs/guides/kokoro-setup.md) - Local text-to-speech
- [Development Setup](docs/tutorials/development-setup.md) - Contributing guide
Full documentation: [voice-mode.readthedocs.io](https://voice-mode.readthedocs.io)
## Links
- **Website**: [getvoicemode.com](https://getvoicemode.com)
- **GitHub**: [github.com/mbailey/voicemode](https://github.com/mbailey/voicemode)
- **PyPI**: [pypi.org/project/voice-mode](https://pypi.org/project/voice-mode/)
- **YouTube**: [@getvoicemode](https://youtube.com/@getvoicemode)
- **Twitter/X**: [@getvoicemode](https://twitter.com/getvoicemode)
## License
MIT - A [Failmode](https://failmode.com) Project
---
mcp-name: com.failmode/voicemode