↓Skip to main content

Claude Code: Install VoiceMode on Debian/Ubuntu

·2 mins

Overview #

VoiceMode enables voice conversations with Claude Code. The automatic installer has issues on Debian x86_64, so this guide covers manual installation of the Whisper speech-to-text service. This guide might also be useful for other Debian related distros like Ubuntu and Mint.

Prerequisites #

# Install system dependencies
sudo apt-get update
sudo apt-get install -y clang cmake g++ make libsdl2-dev portaudio19-dev

# Install uv (Python package manager - provides uvx command)
curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.local/bin/env  # or restart your shell

# Install VoiceMode CLI and Kokoro TTS
uvx voice-mode-install --yes

Manual Whisper Installation #

The automatic installer has a bug on Debian x86_64. Install manually:

# Clone whisper.cpp
mkdir -p ~/.voicemode/services
git clone https://github.com/ggerganov/whisper.cpp.git ~/.voicemode/services/whisper

# Build
cd ~/.voicemode/services/whisper
cmake -B build -DWHISPER_SDL2=ON
cmake --build build -j$(nproc)

# Download model (142MB)
curl -L -o models/ggml-base.bin "https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-base.bin"

Systemd Service (auto-start on boot) #

mkdir -p ~/.config/systemd/user

cat > ~/.config/systemd/user/voicemode-whisper.service << 'EOF'
[Unit]
Description=Whisper.cpp Speech Recognition Server
After=network.target

[Service]
Type=simple
ExecStart=%h/.voicemode/services/whisper/build/bin/whisper-server --host 127.0.0.1 --port 2022 --model %h/.voicemode/services/whisper/models/ggml-base.bin --inference-path /v1/audio/transcriptions
Restart=on-failure
RestartSec=10

[Install]
WantedBy=default.target
EOF

systemctl --user daemon-reload
systemctl --user enable voicemode-whisper.service
systemctl --user start voicemode-whisper.service

Add MCP Server to Claude Code #

claude mcp add --scope user voicemode -- uvx --refresh voice-mode

Verify Installation #

voicemode service status whisper
voicemode service status kokoro

Both should show as running.

Usage #

Restart Claude Code, then:

/voicemode:converse

Service Management #

# Start/stop/restart
systemctl --user start voicemode-whisper.service
systemctl --user stop voicemode-whisper.service
systemctl --user restart voicemode-whisper.service

# View logs
journalctl --user -u voicemode-whisper.service -f

# Kokoro (managed by voicemode)
voicemode service start kokoro
voicemode service stop kokoro

Resources #