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:

# Add the VoiceMode marketplace
claude plugin marketplace add mbailey/voicemode

# Install VoiceMode plugin
claude plugin install voicemode@voicemode

## Install dependencies (CLI, Local Voice Services)

/voicemode:install

# Start talking!
/voicemode:converse

Option 2: Python installer package

Installs dependencies and the VoiceMode Python package.

# 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 --from voice-mode voicemode-mcp-launcher

# 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.

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:

# 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 for all options.

Permissions Setup (Optional)

To use VoiceMode without permission prompts, add to ~/.claude/settings.json:

{
  "permissions": {
    "allow": [
      "mcp__voicemode__converse",
      "mcp__voicemode__service"
    ]
  }
}

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

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

sudo dnf install alsa-lib-devel ffmpeg gcc portaudio portaudio-devel python3-devel

macOS

brew install ffmpeg node portaudio

NixOS

# Use development shell
nix develop github:mbailey/voicemode

# Or install system-wide
nix profile install github:mbailey/voicemode

Alternative Installation Methods

From source

git clone https://github.com/mbailey/voicemode.git
cd voicemode
uv tool install -e .

NixOS system-wide

# 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

export VOICEMODE_SAVE_AUDIO=true
# Files saved to ~/.voicemode/audio/YYYY/MM/

Documentation

Getting Started - Full setup guide
Configuration - All environment variables
Whisper Setup - Local speech-to-text
Kokoro Setup - Local text-to-speech
Development Setup - Contributing guide

Full documentation: voicemode.dev

License

MIT - A Failmode Project

mcp-name: dev.voicemode/voicemode

Release files for voice-mode 8.12.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for voice-mode 8.12.0
File	Size	Uploaded
voice_mode-8.12.0.tar.gz	1.2 MB	Jul 21, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for voice-mode 8.12.0
File	Interpreter	ABI	Platform	Reset
voice_mode-8.12.0-py3-none-any.whl 1.3 MB Jul 21, 2026	Python 3	none	any	Details

Total release size: 2.5 MB

Release files / voice_mode-8.12.0.tar.gz

Download URL	voice_mode-8.12.0.tar.gz
Size	1.2 MB
Tags	Source
SHA-256 checksum How to use checksums	`96f7c0759ef38a24da7391a883da3999f08ac24fb3302a4ca4439e9fcb1f34c7`
BLAKE2b-256 checksum How to use checksums	`22310f5ee3fa205b315c0b8e1aa01f0283984a0213a6431f500c870cda196076`
Upload date	Jul 21, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/mbailey/voicemode
Publishing commit: github.com/mbailey/voicemode/tree/5c1b3e4d9421cd365d039da1d29827a0a83a18c7

Workflow

Publishing configuration: github.com/mbailey/voicemode/blob/5c1b3e4d9421cd365d039da1d29827a0a83a18c7/.github/workflows/publish-pypi-and-mcp.yml
Publishing logs: github.com/mbailey/voicemode/actions/runs/29830975228/attempts/1

Artifact

Subject: voice_mode-8.12.0.tar.gz
SHA-256 checksum: 96f7c0759ef38a24da7391a883da3999f08ac24fb3302a4ca4439e9fcb1f34c7 Verifying attestations

Release files / voice_mode-8.12.0-py3-none-any.whl

Download URL	voice_mode-8.12.0-py3-none-any.whl
Size	1.3 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`6c310bbe1af0d2db0de6adcbd82bc20e1950067e12f84cc0dfd560108d1c039e`
BLAKE2b-256 checksum How to use checksums	`6d07ed0a3e4f4307c9a11deb80e84aec92b646283bf8e67c767a431f90a87981`
Upload date	Jul 21, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/mbailey/voicemode
Publishing commit: github.com/mbailey/voicemode/tree/5c1b3e4d9421cd365d039da1d29827a0a83a18c7

Workflow

Publishing configuration: github.com/mbailey/voicemode/blob/5c1b3e4d9421cd365d039da1d29827a0a83a18c7/.github/workflows/publish-pypi-and-mcp.yml
Publishing logs: github.com/mbailey/voicemode/actions/runs/29830975228/attempts/1

Artifact

Subject: voice_mode-8.12.0-py3-none-any.whl
SHA-256 checksum: 6c310bbe1af0d2db0de6adcbd82bc20e1950067e12f84cc0dfd560108d1c039e Verifying attestations