Skip to content

VoiceMode

Install via: uv tool install voice-mode | getvoicemode.com

PyPI Downloads PyPI Downloads PyPI Downloads

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

  • Linux (fedora, debian/ubuntu)
  • macOS
  • Windows WSL
# 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.

🎬 Demo

Watch VoiceMode in action with Claude Code:

VoiceMode Demo

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 - 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 for details.

System Dependencies

Ubuntu/Debian 
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.
Fedora/RHEL 
sudo dnf install alsa-lib-devel ffmpeg gcc portaudio portaudio-devel python3-devel
macOS 
# 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
Windows (WSL) Follow the Ubuntu/Debian instructions above within WSL.
NixOS VoiceMode includes a flake.nix with all required dependencies. You can either: 1. **Use the development shell** (temporary): 
nix develop github:mbailey/voicemode
2. **Install system-wide** (see Installation section below)

Quick Install

# 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 for step-by-step instructions!

Below are quick configuration snippets. For full installation and setup instructions, see the integration guides above.

Claude Code (CLI) 
claude mcp add --scope user voicemode -- uvx --refresh voice-mode
Or with environment variables: 
claude mcp add --scope user --env OPENAI_API_KEY=your-openai-key voicemode -- uvx --refresh voice-mode

Alternative Installation Options

From source 
git clone https://github.com/mbailey/voicemode.git
cd voicemode
uv tool install -e .
NixOS Installation Options **1. Install with nix profile (user-wide):** 
nix profile install github:mbailey/voicemode
**2. Add to NixOS configuration (system-wide):** 
# In /etc/nixos/configuration.nix
environment.systemPackages = [
  (builtins.getFlake "github:mbailey/voicemode").packages.${pkgs.system}.default
];
**3. Add to home-manager:** 
# In home-manager configuration
home.packages = [
  (builtins.getFlake "github:mbailey/voicemode").packages.${pkgs.system}.default
];
**4. Run without installing:** 
nix run github:mbailey/voicemode

Configuration

Quick Setup

The only required configuration is your OpenAI API key:

export OPENAI_API_KEY="your-key"

Local STT/TTS Services

For privacy-focused or offline usage, VoiceMode supports local speech services:

  • Whisper.cpp - Local speech-to-text with OpenAI-compatible API
  • Kokoro - Local text-to-speech with multiple voice options

These services provide the same API interface as OpenAI, allowing seamless switching between cloud and local processing.

Troubleshooting

Common Issues

  • No microphone access: Check system permissions for terminal/application
  • WSL2 Users: Additional audio packages (pulseaudio, libasound2-plugins) required for microphone access
  • UV not found: Install with curl -LsSf https://astral.sh/uv/install.sh | sh
  • OpenAI API error: Verify your OPENAI_API_KEY is set correctly
  • No audio output: Check system audio settings and available devices

Audio Saving

To save all audio files (both TTS output and STT input):

export VOICEMODE_SAVE_AUDIO=true

Audio files are saved to: ~/.voicemode/audio/YYYY/MM/ with timestamps in the filename.

Documentation

📚 Read the full documentation at voice-mode.readthedocs.io

Getting Started

Development

Service Guides

Community

See Also

License

MIT - A Failmode Project

mcp-name: com.failmode/voicemode