Claude Voice
Local voice interface for Claude Code using VoiceMode MCP.
Features
- 100% Local & Free: No OpenAI API key required
- Privacy-First: Speech processing happens on your machine
- Voice Input: Uses local Whisper for speech-to-text
- Voice Output: Uses local Kokoro TTS with 67 voices
- Powered by Claude Max: AI responses from your Claude subscription
Prerequisites
- Linux (tested on Arch)
- Claude Code CLI installed and authenticated
- cmake for building Whisper
- Python 3.10+
- Claude Max subscription (for AI responses)
Quick Start
Run the automated setup script:```bash
./setup.sh
Or follow the manual installation steps below.
## Manual Installation
### 1. Install uv (Python Package Manager)```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
2. Install cmake
Arch Linux:```bash
sudo pacman -S cmake
**Ubuntu/Debian:**```bash
sudo apt install cmake
3. Install VoiceMode```bash
uvx voice-mode-install
### 4. Add VoiceMode to Claude Code```bash
claude mcp add --scope user voicemode -- uvx --refresh voice-mode
5. Install Local Voice Services
Install Whisper (Speech-to-Text):```bash
voicemode whisper install
**Install Kokoro (Text-to-Speech):**```bash
voicemode kokoro install
6. Fix Whisper OpenAI Compatibility
Edit the Whisper service configuration:```bash
nano ~/.config/systemd/user/voicemode-whisper.service
Find the `ExecStart` line and add `--inference-path "/v1/audio/transcriptions"` to the end:```ini
ExecStart=/home/YOUR_USERNAME/.voicemode/services/whisper/build/bin/whisper-server --host 0.0.0.0 --port 2022 --model /home/YOUR_USERNAME/.voicemode/services/whisper/models/ggml-base.bin --inference-path "/v1/audio/transcriptions"
Reload and restart:```bash
systemctl --user daemon-reload
voicemode whisper stop
voicemode whisper start
### 7. Start Kokoro Manually```bash
cd ~/.voicemode/services/kokoro
bash start-cpu.sh &
Usage
Start Voice Conversation```bash
claude converse
Then speak your question! Claude will:
1. Listen through your microphone (~3s)
2. Transcribe your speech with Whisper (~11-14s on CPU)
3. Generate AI response with Claude (varies)
4. Speak the response with Kokoro (~3-5s)
### Other Commands```bash
# Regular Claude Code (text only)
claude
# Check service status
voicemode whisper status
voicemode kokoro status
# Try different voices (67 available!)
claude converse --voice af_heart
# List available voices
voicemode kokoro --help
Performance
Current Setup (Local CPU):
- Speech-to-Text: ~11-14 seconds (Whisper base model on CPU)
- Text-to-Speech: ~3-5 seconds (Kokoro)
- Total: ~19-20 seconds per turn
Faster Options:
-
Use smaller Whisper model (3-5x faster, slightly less accurate):
bash voicemode whisper model set tiny -
Use OpenAI Cloud Whisper (~1-2 seconds, requires API key):
- Get $5 free credit at https://platform.openai.com/api-keys
- Cost: ~$0.006/minute ($0.36/hour)
- Set:export OPENAI_API_KEY="your-key"
Services
- Whisper: http://127.0.0.1:2022
- Kokoro: http://127.0.0.1:8880
- Kokoro Web Player: http://localhost:8880/web/
Troubleshooting
Whisper not transcribing
Check if Whisper is running with the correct parameters:```bash
ps aux | grep whisper-server
Should show `--inference-path /v1/audio/transcriptions`
If not, restart:```bash
voicemode whisper stop
voicemode whisper start
Kokoro not speaking
Start Kokoro manually:```bash
cd ~/.voicemode/services/kokoro
bash start-cpu.sh &
Check status:```bash
curl http://127.0.0.1:8880/health
Services not auto-starting
Enable services to start on boot:```bash
voicemode whisper enable
voicemode kokoro enable
## Future Enhancements
### Add Web Interface
For phone/laptop browser access:```bash
sudo voicemode livekit install
voicemode livekit frontend install
voicemode livekit frontend start
Architecture```
You speak → Microphone
↓
Whisper (local STT) → Text
↓
Claude Code (MCP) → AI Response
↓
Kokoro (local TTS) → Audio
↓
Speakers → You hear
```
Credits
- VoiceMode: https://github.com/mbailey/voicemode
- Whisper.cpp: https://github.com/ggml-org/whisper.cpp
- Kokoro TTS: https://github.com/remsky/Kokoro-FastAPI
- Claude Code: https://github.com/anthropics/claude-code
License
MIT
Contributing
Pull requests welcome! Please test on your system before submitting.
