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

Metadata

Release files for voice-mode 9.0.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 9.0.0
File	Size	Uploaded	Provenance
voice_mode-9.0.0.tar.gz	1.3 MB	Oct 25, 2026	With provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for voice-mode 9.0.0
File	Interpreter	ABI	Platform	Reset
voice_mode-9.0.0-py3-none-any.whl 1.4 MB Oct 25, 2026 With provenance	Python 3	none	any	Details

Total release size: 2.7 MB

Release files / voice_mode-9.0.0.tar.gz

Download URL	voice_mode-9.0.0.tar.gz
Size	1.3 MB
Tags	Source
SHA-256 checksum How to use checksums	`89955ae4450a7619cd7794ab07759f5b679edffa367b076f0065c2628e9ee02d`
BLAKE2b-256 checksum How to use checksums	`6fb0a340724724af17ae1c4ed5b53feeea6bd49402987f5bfe8def8a85d7db37`
Upload date	Oct 25, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.16`

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/7820b4d6f56d1a806be76afe46028c9b554f4f9c

Workflow

Publishing configuration: github.com/mbailey/voicemode/blob/7820b4d6f56d1a806be76afe46028c9b554f4f9c/.github/workflows/publish-pypi-and-mcp.yml
Publishing logs: github.com/mbailey/voicemode/actions/runs/40175360441/attempts/1

Artifact

Subject: voice_mode-9.0.0.tar.gz
SHA-256 checksum: 89955ae4450a7619cd7794ab07759f5b679edffa367b076f0065c2628e9ee02d Verifying attestations

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

Download URL	voice_mode-9.0.0-py3-none-any.whl
Size	1.4 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`0ac790b99cb6a77ecd61d7d0833e304cbe57ff6b39b7139826b3026b79903cc0`
BLAKE2b-256 checksum How to use checksums	`ac6759b036434a7716cd8598bbc5d8aaf14f3950f07954ba97a10307fa69600c`
Upload date	Oct 25, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.16`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/mbailey/voicemode
Publishing commit: github.com/mbailey/voicemode/tree/7820b4d6f56d1a806be76afe46028c9b554f4f9c

Workflow

Publishing configuration: github.com/mbailey/voicemode/blob/7820b4d6f56d1a806be76afe46028c9b554f4f9c/.github/workflows/publish-pypi-and-mcp.yml
Publishing logs: github.com/mbailey/voicemode/actions/runs/40175360441/attempts/1

Artifact

Subject: voice_mode-9.0.0-py3-none-any.whl
SHA-256 checksum: 0ac790b99cb6a77ecd61d7d0833e304cbe57ff6b39b7139826b3026b79903cc0 Verifying attestations

Security for voice-mode 9.0.0

Report project as malware

Provenance

Full provenance

All 2 files in this release have been uploaded with provenance metadata.

Attestation for voice_mode-9.0.0.tar.gz

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/mbailey/voicemode
Publishing commit: github.com/mbailey/voicemode/tree/7820b4d6f56d1a806be76afe46028c9b554f4f9c

Workflow

Publishing configuration: github.com/mbailey/voicemode/blob/7820b4d6f56d1a806be76afe46028c9b554f4f9c/.github/workflows/publish-pypi-and-mcp.yml
Publishing logs: github.com/mbailey/voicemode/actions/runs/40175360441/attempts/1

Artifact

Subject: voice_mode-9.0.0.tar.gz
SHA-256 checksum: 89955ae4450a7619cd7794ab07759f5b679edffa367b076f0065c2628e9ee02d Verifying attestations

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.