Agent skill

voicemode

Voice interaction for Claude Code. Use when users mention voice mode, speak, talk, converse, voice status, or voice troubleshooting.

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/development/voicemode

SKILL.md

First-Time Setup

If VoiceMode isn't working or MCP fails to connect, run:

/voicemode:install

After install, reconnect MCP: /mcp → select voicemode → "Reconnect" (or restart Claude Code).

VoiceMode

Natural voice conversations with Claude Code using speech-to-text (STT) and text-to-speech (TTS).

Note: The Python package is voice-mode (hyphen), but the CLI command is voicemode (no hyphen).

When to Use MCP vs CLI

Task Use Why
Voice conversations MCP voicemode:converse Faster - server already running
Service start/stop MCP voicemode:service Works within Claude Code
Installation CLI voice-mode-install One-time setup
Configuration CLI voicemode config Edit settings directly
Diagnostics CLI voicemode diag Administrative tasks

Usage

Use the converse MCP tool to speak to users and hear their responses:

python
# Speak and listen for response (most common usage)
voicemode:converse("Hello! What would you like to work on?")

# Speak without waiting (for narration while working)
voicemode:converse("Searching the codebase now...", wait_for_response=False)

For most conversations, just pass your message - defaults handle everything else.

Parameter Default Description
message required Text to speak
wait_for_response true Listen after speaking
voice auto TTS voice

For all parameters, see Converse Parameters.

Best Practices

  1. Narrate without waiting - Use wait_for_response=False when announcing actions
  2. One question at a time - Don't bundle multiple questions in voice mode
  3. Check status first - Verify services are running before starting conversations
  4. Let VoiceMode auto-select - Don't hardcode providers unless user has preference
  5. First run is slow - Model downloads happen on first start (2-5 min), then instant

Check Status

bash
voicemode service status          # All services
voicemode service status whisper  # Specific service

Shows service status including running state, ports, and health.

Installation

bash
# Install VoiceMode CLI and configure services
uvx voice-mode-install --yes

# Install local services (Apple Silicon recommended)
voicemode service install whisper
voicemode service install kokoro

See Getting Started for detailed steps.

Service Management

python
# Start/stop services
voicemode:service("whisper", "start")
voicemode:service("kokoro", "start")

# View logs for troubleshooting
voicemode:service("whisper", "logs", lines=50)
Service Port Purpose
whisper 2022 Speech-to-text
kokoro 8880 Text-to-speech
livekit 7880 Real-time rooms

Actions: status, start, stop, restart, logs, enable, disable

Configuration

bash
voicemode config list                           # Show all settings
voicemode config set VOICEMODE_TTS_VOICE nova   # Set default voice
voicemode config edit                           # Edit config file

Config file: ~/.voicemode/voicemode.env

See Configuration Guide for all options.

DJ Mode

Background music during VoiceMode sessions with track-level control.

bash
# Core playback
voicemode dj play /path/to/music.mp3  # Play a file or URL
voicemode dj status                    # What's playing
voicemode dj pause                     # Pause playback
voicemode dj resume                    # Resume playback
voicemode dj stop                      # Stop playback

# Navigation and volume
voicemode dj next                      # Skip to next chapter
voicemode dj prev                      # Go to previous chapter
voicemode dj volume 30                 # Set volume to 30%

# Music For Programming
voicemode dj mfp list                  # List available episodes
voicemode dj mfp play 49               # Play episode 49
voicemode dj mfp sync                  # Convert CUE files to chapters

# Music library
voicemode dj find "daft punk"          # Search library
voicemode dj library scan              # Index ~/Audio/music
voicemode dj library stats             # Show library info

# Play history and favorites
voicemode dj history                   # Show recent plays
voicemode dj favorite                  # Toggle favorite on current track

Configuration: Set VOICEMODE_DJ_VOLUME in ~/.voicemode/voicemode.env to customize startup volume (default: 50%).

CLI Cheat Sheet

bash
# Service management
voicemode service status            # All services
voicemode service start whisper     # Start a service
voicemode service logs kokoro       # View logs

# Diagnostics
voicemode deps                      # Check dependencies
voicemode diag info                 # System info
voicemode diag devices              # Audio devices

# History search
voicemode history search "keyword"
voicemode history play <exchange_id>

# DJ Mode
voicemode dj play <file|url>        # Start playback
voicemode dj status                 # What's playing
voicemode dj next/prev              # Navigate chapters
voicemode dj stop                   # Stop playback
voicemode dj mfp play 49            # Music For Programming

Documentation Index

Topic Link
Converse Parameters All Parameters
Installation Getting Started
Configuration Configuration Guide
Claude Code Plugin Plugin Guide
Whisper STT Whisper Setup
Kokoro TTS Kokoro Setup
Pronunciation Pronunciation Guide
Troubleshooting Troubleshooting
CLI Reference CLI Docs
DJ Mode Background Music

Didn't find tool you were looking for?

Be as detailed as possible for better results