Skip to content

README-improved.md

Latest commit

 

History

History
234 lines (166 loc) · 6.86 KB

README-improved.md

File metadata and controls

234 lines (166 loc) · 6.86 KB

Voice Mode

Transform your AI coding experience with natural voice conversations. Talk to Claude like a colleague, not a chatbot.

Quick Install: uvx voice-mode | Docs: getvoicemode.com | Built for Claude Code

PyPI Downloads PyPI Downloads Documentation

What if you could just... talk to Claude?

Imagine explaining a bug out loud and hearing Claude walk you through the fix. Or having a back-and-forth design discussion while you code. Voice Mode makes Claude Code feel like pair programming with a real person.

In 30 seconds: Install Voice Mode and say "Hey Claude, let's debug this together" - and actually have a conversation.

🎬 See It In Action

Watch Voice Mode transform how you work with Claude Code:

Voice Mode Demo

Why Voice Mode Changes Everything

Before Voice Mode 😔

  • Type long explanations of bugs
  • Copy-paste error messages back and forth
  • Lose context switching between docs and code
  • Feel isolated debugging alone
  • Wait for responses without knowing if Claude understood

After Voice Mode 🚀

  • "Claude, this function is throwing an error" paste "What's wrong?"
  • "Walk me through this architecture while I look at the code"
  • "Let's brainstorm a better approach" (actual back-and-forth!)
  • Feels like pair programming with a senior developer
  • Natural conversation flow - Claude waits for your response

What Users Say

"I can't imagine coding without Voice Mode now. It's like having a senior developer sitting next to me all the time." - @jameskilroe

"Game changer. I explain problems 10x faster by talking than typing. Voice Mode is the future of AI coding." - @adamgrant

"Finally, AI that actually listens. The conversation flow is so natural I forget I'm talking to an AI." - @stephsmith

Get Started in 30 Seconds (Claude Code)

# One command installs everything:
curl -O https://getvoicemode.com/install.sh && bash install.sh

# Then just run:
claude converse

That's it! Voice Mode is now ready. The installer handles all dependencies, configures Claude Code, and sets up your system for voice conversations.

📦 Other installation methods

Using UV (recommended for manual install)

claude mcp add voice-mode -- uvx voice-mode

Using pip

pip install voice-mode
claude mcp add voice-mode -- voicemode

From source

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

Perfect For You If...

✅ You use Claude Code for development
✅ You think better when talking through problems
✅ You want faster, more natural AI interactions
✅ You're tired of typing long explanations
✅ You miss pair programming with real humans

Core Features

  • 🎙️ Natural conversations - Claude waits for your response, creating real dialogue
  • ⚡ Instant responses - Hear Claude's voice in under a second
  • 🔒 Privacy-first - Use OpenAI or run everything locally
  • 🎯 Just works - Auto-detects your mic and speakers
  • 🤝 Claude Code optimized - Designed specifically for Claude Code users

Example Conversations

Once installed, try these natural interactions:

👨‍💻 Programming

You: "Claude, let's debug this error together"
Claude: "I'll help you debug that. Can you tell me what error you're seeing?"
You: [Explain the error naturally]
Claude: [Walks you through the solution]

🏗️ Architecture

You: "I need to design a caching system, let's talk through the options"
Claude: [Discusses options interactively, asking clarifying questions]

📝 Code Review

You: "Review this function and tell me what could be better"
Claude: [Provides feedback, then asks if you want to discuss specific points]

Simple Requirements

  1. 🎤 Computer with microphone and speakers
  2. 🔑 OpenAI API Key (optional - Voice Mode can install free local services)

Runs on: Linux • macOS • Windows (WSL) • NixOS | Python: 3.10+

🔧 System dependencies

Ubuntu/Debian

sudo apt update
sudo apt install -y python3-dev portaudio19-dev ffmpeg

macOS

brew install portaudio ffmpeg

Fedora/RHEL

sudo dnf install python3-devel portaudio-devel ffmpeg

Also Works With

While Voice Mode is optimized for Claude Code, it also supports:

🔧 Other AI coding assistants
  • Claude Desktop - Desktop application
  • Cursor - AI-first code editor
  • VS Code - With MCP preview
  • Cline - Autonomous coding agent
  • Windsurf - Agentic IDE
  • Continue - Open-source assistant
  • Zed - High-performance editor
  • Roo Code - AI dev team
  • Gemini CLI - Google's CLI tool

See Integration Guides for setup instructions.

Configuration

Voice Mode works out of the box with just your OpenAI key:

export OPENAI_API_KEY="your-key"
⚙️ Advanced configuration

Use Local Services (Free & Private)

# Voice Mode can install these for you:
export STT_BASE_URL="http://127.0.0.1:2022/v1"  # Local Whisper
export TTS_BASE_URL="http://127.0.0.1:8880/v1"  # Local Kokoro

Custom Voices

export TTS_VOICE="nova"  # OpenAI voices
# Or create ~/voices.txt with your preferences

Debug Mode

export VOICEMODE_DEBUG="true"
export VOICEMODE_SAVE_AUDIO="true"  # Save recordings

See Configuration Guide for all options.

Troubleshooting

🐛 Common issues
  • No microphone access: Check terminal has mic permissions in System Settings
  • API error: Verify your OPENAI_API_KEY is set correctly
  • WSL2 audio: See WSL2 Microphone Guide

Run diagnostics:

python scripts/diagnose-audio.py

Links

License

MIT - A Failmode Project

Transform your coding experience. Install Voice Mode and start talking to Claude naturally.