by mbailey
Natural voice conversations with Claude Code
# Add to your Claude Code skills
git clone https://github.com/mbailey/voicemodeGuides for using mcp servers skills like voicemode.
Last scanned: 4/30/2026
{
"issues": [],
"status": "PASSED",
"scannedAt": "2026-04-30T06:30:49.412Z",
"semgrepRan": false,
"npmAuditRan": true,
"pipAuditRan": true
}No comments yet. Be the first to share your thoughts!
Top skills in this category by stars
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:
Requirements: Computer with microphone and speakers
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
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.
Platforms: Linux, macOS, Windows (WSL), NixOS Python: 3.10-3.14
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.
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.
For privacy or offline use, install local speech services:
These provide the same API as OpenAI, so VoiceMode switches seamlessly between them.
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.
sudo dnf install alsa-lib-devel ffmpeg gcc portaudio portaudio-devel python3-devel
brew install ffmpeg node portaudio
# Use development shell
nix develop github:mbailey/voicemode
# Or install system-wide
nix profile install github:mbailey/voicemode
git clone https://github.com/mbailey/voicemode.git
cd voicemode
uv tool install -e .
# In /etc/nixos/configuration.nix
environment.systemPackages = [
(builtins.getFlake "github:mbailey/voicemode").packages.${pkgs.system}.default
];
| 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 |
export VOICEMODE_SAVE_AUDIO=true
# Files saved to ~/.voicemode/audio/YYYY/MM/
Full documentation: voice-mode.readthedocs.io
MIT - A Failmode Project
mcp-name: com.failmode/voicemode