voicemode

# VoiceMode > **Install via:** `uv tool install voice-mode` | [getvoicemode.com](https://getvoicemode.com) [](https://pepy.tech/project/voice-mode) [](https://pepy.tech/project/voice-mode) [](https://pepy.tech/project/voice-mode) Natural voice conversations for AI assistants. VoiceMode brings human-like voice interactions to Claude Code, AI code editors through the Model Context Protocol (MCP). ## 🖥️ Compatibility **Runs on:** Linux • macOS • Windows (WSL) • NixOS | **Python:** 3.10-3.14 ## ✨ Features - **🎙️ Natural Voice Conversations** with Claude Code - ask questions and hear responses - **🗣️ Supports local Voice Models** - works with any OpenAI API compatible STT/TTS services - **⚡ Real-time** - low-latency voice interactions with automatic transport selection - **🔧 MCP Integration** - seamless with Claude Code (and other MCP clients) - **🎯 Silence detection** - automatically stops recording when you stop speaking (no more waiting!) - **🔄 Multiple transports** - local microphone or LiveKit room-based communication (optional) ## 🎯 Simple Requirements **All you need to get started:** 1. **🎤 Computer with microphone and speakers** 2. **🔑 OpenAI API Key** (Recommended, if only as a backup for local services) ## Quick Start ### Install VoiceMode and dependencies with UV (Recommended) - Linux (fedora, debian/ubuntu) - macOS - Windows WSL ```bash # Install VoiceMode MCP python package and dependencies curl -LsSf https://astral.sh/uv/install.sh | sh uvx voice-mode-install # While local voice services can be installed automatically, we recommend # providing an OpenAI API key as a fallback in case local services are unavailable export OPENAI_API_KEY=your-openai-key # Optional but recommended # Add VoiceMode to Claude claude mcp add --scope user voicemode -- uvx --refresh voice-mode # Start a voice conversation claude converse ``` ### Manual Installation For manual setup steps, see the [Getting Started Guide](docs/tutorials/getting-started.md). ## 🎬 Demo Watch VoiceMode in action with Claude Code: [](https://www.youtube.com/watch?v=cYdwOD_-dQc) The `converse` function makes voice interactions natural - it automatically waits for your response by default, creating a real conversation flow. ## Installation ### Prerequisites - Python 3.10-3.14 - [Astral UV](https://github.com/astral-sh/uv) - Package manager (install with `curl -LsSf https://astral.sh/uv/install.sh | sh`) - OpenAI API Key (or compatible service) > **Note on LiveKit:** LiveKit integration is optional and requires Python 3.10-3.13 (Python 3.14 support pending upstream dependencies). Install with: `uv tool install voice-mode[livekit]`. See [LiveKit Integration Guide](docs/guides/livekit-setup.md) for details. #### System Dependencies <details> <summary><strong>Ubuntu/Debian</strong></summary> ```bash sudo apt update sudo apt install -y ffmpeg gcc libasound2-dev libasound2-plugins libportaudio2 portaudio19-dev pulseaudio pulseaudio-utils python3-dev ``` **Note for WSL2 users**: WSL2 requires additional audio packages (pulseaudio, libasound2-plugins) for microphone access. </details> <details> <summary><strong>Fedora/RHEL</strong></summary> ```bash sudo dnf install alsa-lib-devel ffmpeg gcc portaudio portaudio-devel python3-devel ``` </details> <details> <summary><strong>macOS</strong></summary> ```bash # Install Homebrew if not already installed /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" # Install dependencies brew install ffmpeg node portaudio ``` </details> <details> <summary><strong>Windows (WSL)</strong></summary> Follow the Ubuntu/Debian instructions above within WSL. </details> <details> <summary><strong>NixOS</strong></summary> VoiceMode includes a flake.nix with all required dependencies. You can either: 1. **Use the development shell** (temporary): ```bash nix develop github:mbailey/voicemode ``` 2. **Install system-wide** (see Installation section below) </details> ### Quick Install ```bash # Using Claude Code (recommended) claude mcp add --scope user voicemode uvx --refresh voice-mode ``` ### Configuration for AI Coding Assistants > 📖 **Looking for detailed setup instructions?** Check our comprehensive [Getting Started Guide](docs/tutorials/getting-started.md) for step-by-step instructions! Below are quick configuration snippets. For full installation and setup instructions, see the integration guides above. <details> <summary><strong>Claude Code (CLI)</strong></summary> ```bash claude mcp add --scope user voicemode -- uvx --refresh voice-mode ``` Or with environment variables: ```bash claude mcp add --scope user --env OPENAI_API_KEY=your-openai-key voicemode -- uvx