### Install and Start Local Services

Source: https://voicemode.readthedocs.io/en/latest/tutorials/development-setup

Installs and starts local services like Whisper and Kokoro for development without requiring API keys.

```bash
# Or manually
voicemode whisper install
voicemode kokoro install

# Or manually
voicemode whisper start
voicemode kokoro start
```

--------------------------------

### Install and Start Tailscale

Source: https://voicemode.readthedocs.io/en/latest/guides/serve-configuration

Installs Tailscale using Homebrew on macOS and starts the service.

```bash
# macOS
brew install tailscale

# Start Tailscale
sudo tailscale up
```

--------------------------------

### Starting Services Examples

Source: https://voicemode.readthedocs.io/en/latest/reference/cli/service-commands

Demonstrates starting the Whisper and Kokoro services. The output confirms successful startup and provides the process ID (PID) for Whisper.

```bash
$ voicemode whisper start
✅ Whisper started successfully (PID: 54321)

$ voicemode kokoro start  
✅ Kokoro started
```

--------------------------------

### Install and Enable Services

Source: https://voicemode.readthedocs.io/en/latest/reference/cli

Installs and enables the Whisper and Kokoro services for a full local setup.

```bash
# Full local setup
voicemode whisper install
voicemode kokoro install
voicemode whisper enable
voicemode kokoro enable
```

--------------------------------

### Install, Start, and Check Kokoro Service

Source: https://voicemode.readthedocs.io/en/latest/guides/kokoro-setup

Basic commands to install, start, and check the status of the Kokoro service using the VoiceMode CLI.

```bash
# Install kokoro service
voicemode kokoro install

# Start the service
voicemode kokoro start

# Check status
voicemode kokoro status

```

--------------------------------

### Service Management Examples (Enable/Disable)

Source: https://voicemode.readthedocs.io/en/latest/reference/cli/service-commands

Shows how to enable the Kokoro service to start automatically at login and disable the Whisper service, removing it from automatic startup.

```bash
$ voicemode kokoro enable
✅ Kokoro service enabled. It will start automatically at login.
Plist: /Users/user/Library/LaunchAgents/com.voicemode.kokoro.plist

$ voicemode whisper disable
✅ Whisper service disabled and removed
```

--------------------------------

### Check Python and Install uvx

Source: https://voicemode.readthedocs.io/en/latest/guides/kokoro-setup

Prerequisites for manual Kokoro installation. Ensure Python 3.8+ is installed and then install the uvx package manager.

```bash
# Ensure Python 3.8+ is installed
python3 --version

# Install uvx
pip install uvx

```

--------------------------------

### Start MCP Server (Default Behavior)

Source: https://voicemode.readthedocs.io/en/latest/reference/cli/service-commands

This command preserves the existing behavior by starting the MCP server.

```bash
voicemode              # Starts MCP server (existing behavior)
```

--------------------------------

### Pre-commit Hooks Setup

Source: https://voicemode.readthedocs.io/en/latest/tutorials/development-setup

Installs and configures pre-commit hooks for automated checks before committing code.

```bash
# Install pre-commit
pip install pre-commit

# Install hooks
pre-commit install

# Run manually
pre-commit run --all-files
```

--------------------------------

### Install and Manage Whisper Service

Source: https://voicemode.readthedocs.io/en/latest/guides/whisper-setup

Commands to install, list, switch, and start the Whisper service with different models. Supports automatic installation and Core ML on Apple Silicon.

```bash
# Install whisper service with default base model (includes Core ML on Apple Silicon!)
voicemode whisper service install

# Install with a different model
voicemode whisper service install --model large-v3

# List available models and their status
voicemode whisper model --all

# Switch to a different model (auto-installs if needed)
voicemode whisper model large-v2

# Start the service
voicemode whisper service start
```

--------------------------------

### Start VoiceMode Server

Source: https://voicemode.readthedocs.io/en/latest/reference/cli

Starts the main VoiceMode server process.

```bash
# Start MCP server
voicemode
```

--------------------------------

### User Configuration File Example

Source: https://voicemode.readthedocs.io/en/latest/reference/environment

Set user-specific environment variables in `~/.voicemode/voicemode.env`. This example configures API keys, voices, and debug mode.

```bash
export OPENAI_API_KEY="sk-..."
export VOICEMODE_VOICES="nova,shimmer"
export VOICEMODE_DEBUG=false

```

--------------------------------

### Project Configuration File Example

Source: https://voicemode.readthedocs.io/en/latest/reference/environment

Define project-specific environment variables in `.voicemode.env` located in the project root. This example sets available voices and TTS speed.

```bash
export VOICEMODE_VOICES="onyx"
export VOICEMODE_TTS_SPEED=0.9

```

--------------------------------

### Install VoiceMode and Dependencies

Source: https://voicemode.readthedocs.io/en/latest/guides/claude-code-plugin

Install VoiceMode services and dependencies using the provided slash command. This sets up Whisper.cpp, Kokoro, and FFmpeg.

```bash
/voicemode:install
```

--------------------------------

### Viewing Logs Example

Source: https://voicemode.readthedocs.io/en/latest/reference/cli/service-commands

Example of viewing the last 20 log entries for the Kokoro service, displaying timestamps and log messages.

```bash
$ voicemode kokoro logs --lines 20
=== Last 20 log entries for kokoro ===
[2025-08-11 15:30:42] Starting Kokoro FastAPI server...
[2025-08-11 15:30:43] Server listening on 0.0.0.0:8880
...
```

--------------------------------

### Install and Manage Local Voice Services

Source: https://voicemode.readthedocs.io/en/latest/tutorials/getting-started

Installs, starts, and checks the status of local Speech-to-Text (Whisper) and Text-to-Speech (Kokoro) services for enhanced privacy.

```bash
# Install local services
voicemode service install whisper   # Speech-to-text
voicemode service install kokoro    # Text-to-speech

# Start services
voicemode service start whisper
voicemode service start kokoro

# Check status of all services
voicemode service status

```

--------------------------------

### User Configuration File Example

Source: https://voicemode.readthedocs.io/en/latest/guides/configuration

Example of the `voicemode.env` file located in the user's home directory. This file uses shell export format for configuration.

```bash
# ~/.voicemode/voicemode.env example
export OPENAI_API_KEY="sk-..."
export VOICEMODE_VOICES="af_sky,nova"
export VOICEMODE_DEBUG=false

```

--------------------------------

### Install Kokoro using Claude Code

Source: https://voicemode.readthedocs.io/en/latest/guides/kokoro-setup

An alternative method to install Kokoro by using Claude Code to execute the installation command.

```bash
# Or using Claude Code
claude converse "Please install kokoro-fastapi"

```

--------------------------------

### Recommended Minimum Setup

Source: https://voicemode.readthedocs.io/en/latest/guides/selective-tool-loading

Configure VoiceMode to load 'converse' and 'service' tools for voice conversation and basic service management.

```bash
export VOICEMODE_TOOLS_ENABLED=converse,service
```

--------------------------------

### Clone Repository and Install in Development Mode

Source: https://voicemode.readthedocs.io/en/latest/tutorials/development-setup

Clones the VoiceMode repository from GitHub and installs it in development mode using UV.

```bash
# Clone your fork (replace YOUR-USERNAME)
git clone https://github.com/YOUR-USERNAME/voicemode
cd voicemode

# Install in development mode
uv tool install -e .
```

--------------------------------

### Start VoiceMode Server (Localhost)

Source: https://voicemode.readthedocs.io/en/latest/guides/serve-configuration

Starts the VoiceMode server, accessible only from the local machine by default. The server will be available at http://127.0.0.1:8765/mcp.

```bash
voicemode serve
```

--------------------------------

### Install Kokoro with VoiceMode CLI

Source: https://voicemode.readthedocs.io/en/latest/guides/kokoro-setup

Use the VoiceMode CLI to automatically install Kokoro with default settings. This includes cloning the repository, setting up startup, and downloading models.

```bash
# Install kokoro with default settings
voicemode kokoro install

```

--------------------------------

### Install VoiceMode via uv

Source: https://voicemode.readthedocs.io/en/latest/guides/claude-code-plugin

Alternatively, install VoiceMode and its services directly using the uv package manager.

```bash
uv tool install voice-mode
voicemode whisper service install
voicemode kokoro install
```

--------------------------------

### Install VoiceMode Plugin for Claude Code

Source: https://voicemode.readthedocs.io/en/latest

Use this command to add the VoiceMode marketplace and install the plugin within Claude Code. This is the recommended quick start option for Claude Code users.

```bash
# 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
```

--------------------------------

### Install VoiceMode from Source

Source: https://voicemode.readthedocs.io/en/latest

Clones the VoiceMode repository and installs it using the `uv` tool. This method is for users who want to build or modify the source code.

```bash
git clone https://github.com/mbailey/voicemode.git
cd voicemode
uv tool install -e .
```

--------------------------------

### Manual Whisper Installation on Linux

Source: https://voicemode.readthedocs.io/en/latest/guides/whisper-setup

Clone and build whisper.cpp from source, then download a specific model manually for Linux.

```bash
# Clone and build whisper.cpp
git clone https://github.com/ggerganov/whisper.cpp
cd whisper.cpp
make

# Download model
mkdir -p ~/.voicemode/models/whisper
cd ~/.voicemode/models/whisper
wget https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v2.bin
```

--------------------------------

### Quick Status Check Example

Source: https://voicemode.readthedocs.io/en/latest/reference/cli/service-commands

Example of checking the status of the Kokoro service, showing its running state, PID, port, resource usage, uptime, and service file version.

```bash
$ voicemode kokoro status
✅ Kokoro is running
   PID: 12345
   Port: 8880
   CPU: 0.1%
   Memory: 8.9 MB
   Uptime: 2h 15m 30s
   Service files: v1.1.1 (latest)
```

--------------------------------

### Full Development Setup

Source: https://voicemode.readthedocs.io/en/latest/guides/selective-tool-loading

Configure VoiceMode to load essential tools for development and debugging, including converse, service, statistics, and configuration management.

```bash
export VOICEMODE_TOOLS_ENABLED=converse,service,statistics,configuration_management,providers
```

--------------------------------

### Automatic Whisper Installation

Source: https://voicemode.readthedocs.io/en/latest/guides/whisper-setup

Use the VoiceMode installation tool to automatically set up Whisper.cpp with GPU support and download the specified model.

```bash
# Install with default base model (142MB) - good balance of speed and accuracy
voicemode whisper service install

# Install with a specific model
voicemode whisper service install --model small
```

--------------------------------

### Start Default MCP Server

Source: https://voicemode.readthedocs.io/en/latest/reference/cli

Starts the MCP server using the default stdio transport. This is the basic command to initiate the server without specific configurations.

```bash
voicemode

```

--------------------------------

### Verify FFmpeg Installation

Source: https://voicemode.readthedocs.io/en/latest/guides/claude-code-plugin

Verify that FFmpeg is installed on your system. This is a dependency for audio processing in VoiceMode.

```bash
which ffmpeg
```

--------------------------------

### Correct Permissions Syntax Example

Source: https://voicemode.readthedocs.io/en/latest/guides/permissions

Shows the correct JSON structure for granting permissions, using the `permissions.allow` key.

```json
{
  "permissions": {
    "allow": ["mcp__voicemode__converse"]
  }
}

```

--------------------------------

### Verify uvx Installation

Source: https://voicemode.readthedocs.io/en/latest/guides/kokoro-setup

Check if the 'uvx' command-line tool is installed and accessible in your system's PATH.

```bash
which uvx
```

--------------------------------

### Install UV Package Manager

Source: https://voicemode.readthedocs.io/en/latest/tutorials/development-setup

Installs the UV package manager using a curl script or pip. UV is recommended for VoiceMode development.

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

```bash
pip install uv
```

--------------------------------

### Quick Setup for VoiceMode Permissions

Source: https://voicemode.readthedocs.io/en/latest/guides/permissions

Add this JSON configuration to `~/.claude/settings.json` to allow VoiceMode conversations and service management without prompts.

```json
{
  "permissions": {
    "allow": [
      "mcp__voicemode__converse",
      "mcp__voicemode__service"
    ]
  }
}

```

--------------------------------

### Manage Kokoro TTS Service

Source: https://voicemode.readthedocs.io/en/latest/reference/cli

Commands for installing, uninstalling, starting, stopping, restarting, and managing the status of the Kokoro TTS service. Also includes options for enabling/disabling the service and listing available voices.

```bash
voicemode kokoro install
```

```bash
voicemode kokoro uninstall
```

```bash
voicemode kokoro start
```

```bash
voicemode kokoro stop
```

```bash
voicemode kokoro restart
```

```bash
voicemode kokoro status
```

```bash
voicemode kokoro enable
```

```bash
voicemode kokoro disable
```

```bash
voicemode kokoro voices
```

```bash
voicemode kokoro logs --follow
```

--------------------------------

### Install Development Dependencies

Source: https://voicemode.readthedocs.io/en/latest/tutorials/development-setup

Installs project dependencies in development mode using UV, particularly useful for resolving import errors.

```bash
uv pip install -e .
```

--------------------------------

### Manual Whisper Installation on macOS

Source: https://voicemode.readthedocs.io/en/latest/guides/whisper-setup

Install Whisper.cpp via Homebrew and download a specific model manually for macOS.

```bash
# Install via Homebrew
brew install whisper.cpp

# Download model
mkdir -p ~/.voicemode/models/whisper
cd ~/.voicemode/models/whisper
curl -LO https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v2.bin
```

--------------------------------

### Install VoiceMode and Configure for Claude Code

Source: https://voicemode.readthedocs.io/en/latest/tutorials/getting-started

Installs the UV package manager, VoiceMode, and adds it to Claude Code's MCP. This process also installs system dependencies and optionally local voice services.

```bash
# Install UV package manager (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install VoiceMode and configure services
uvx voice-mode-install

# Add to Claude Code MCP
claude mcp add --scope user voicemode -- uvx --refresh voice-mode

```

--------------------------------

### Install and Enable Local Voice Services

Source: https://voicemode.readthedocs.io/en/latest/guides/configuration

Install and enable local services like Kokoro and Whisper for offline voice processing. VoiceMode auto-detects these services.

```bash
# Install local services
voicemode service install kokoro
voicemode service install whisper

# Enable auto-start at boot/login
voicemode service enable kokoro
voicemode service enable whisper

# VoiceMode auto-detects them!

```

--------------------------------

### Run VoiceMode as a Service

Source: https://voicemode.readthedocs.io/en/latest/tutorials/getting-started

Start the VoiceMode HTTP server for remote access and enable it to automatically start on boot. This is useful for persistent operation.

```bash
# Start the VoiceMode HTTP server
voicemode service start voicemode
```

```bash
# Enable auto-start at boot/login
voicemode service enable voicemode
```

```bash
# Check all services
voicemode service status
```

--------------------------------

### Start VoiceMode Server (All Interfaces)

Source: https://voicemode.readthedocs.io/en/latest/guides/serve-configuration

Binds the VoiceMode server to all network interfaces, allowing connections from other devices on the local network. Use this to enable local network access.

```bash
voicemode serve --host 0.0.0.0
```

--------------------------------

### voicemode (default command)

Source: https://voicemode.readthedocs.io/en/latest/reference/cli

Starts the MCP server using the standard input/output (stdio) transport.

```APIDOC
## Core Commands

### voicemode (default)

Start the MCP server (stdio transport)

```
voicemode
```
```

--------------------------------

### Local-First Voice Setup

Source: https://voicemode.readthedocs.io/en/latest/guides/selecting-voices

Configure `VOICEMODE_VOICES` to prioritize local Kokoro voices like 'af_sky' and 'am_adam' before cloud options.

```shell
VOICEMODE_VOICES=af_sky,am_adam,nova

```

--------------------------------

### .voicemode.env File Configuration

Source: https://voicemode.readthedocs.io/en/latest/guides/selective-tool-loading

Recommended method: Configure tool loading by creating or editing the ~/.voicemode/voicemode.env file. This example sets up whitelist mode.

```dotenv
# Whitelist mode - only load specified tools (most efficient)
VOICEMODE_TOOLS_ENABLED=converse,service
```

--------------------------------

### Cloud-First Voice Setup

Source: https://voicemode.readthedocs.io/en/latest/guides/selecting-voices

Configure `VOICEMODE_VOICES` to prioritize cloud OpenAI voices like 'nova' and 'shimmer' before local options.

```shell
VOICEMODE_VOICES=nova,shimmer,af_sky

```

--------------------------------

### Install VoiceMode Plugin

Source: https://voicemode.readthedocs.io/en/latest/guides/claude-code-plugin

Install the VoiceMode plugin from the added marketplace. This enables voice capabilities within Claude Code.

```bash
# Install the plugin
claude plugin install voicemode@mbailey
```

--------------------------------

### Enable Debug Logging for Troubleshooting

Source: https://voicemode.readthedocs.io/en/latest/guides/serve-configuration

Starts the VoiceMode server with debug logging enabled to help diagnose connection issues.

```bash
voicemode serve --log-level debug
```

--------------------------------

### Start VoiceMode Server (Specific IP Range)

Source: https://voicemode.readthedocs.io/en/latest/guides/serve-configuration

Starts the VoiceMode server and allows connections only from devices within the specified IP address range. This enhances security for network access.

```bash
voicemode serve --host 0.0.0.0 --allow-ip 192.168.1.0/24
```

--------------------------------

### Start VoiceMode Server (Tailscale)

Source: https://voicemode.readthedocs.io/en/latest/guides/serve-configuration

Configures the VoiceMode server to allow connections from devices on the Tailscale network. This is useful for secure cloud access.

```bash
voicemode serve --host 0.0.0.0 --allow-tailscale
```

--------------------------------

### Voice with Statistics Setup

Source: https://voicemode.readthedocs.io/en/latest/guides/selective-tool-loading

Configure VoiceMode to load 'converse', 'service', and 'statistics' tools to track conversation metrics.

```bash
export VOICEMODE_TOOLS_ENABLED=converse,service,statistics
```

--------------------------------

### Install VoiceMode System Dependencies on Fedora/RHEL

Source: https://voicemode.readthedocs.io/en/latest

Installs required system packages for VoiceMode on Fedora and RHEL-based systems, including ffmpeg, build tools, and audio libraries.

```bash
sudo dnf install alsa-lib-devel ffmpeg gcc portaudio portaudio-devel python3-devel
```

--------------------------------

### Install VoiceMode CLI Tool

Source: https://voicemode.readthedocs.io/en/latest/tutorials/getting-started

Installs the VoiceMode CLI tool using pip or from source. This allows you to use VoiceMode's features directly from your terminal.

```bash
# Install with pip
uv tool install voice-mode

# Or install from source in editable mode
git clone https://github.com/mbailey/voicemode
cd voicemode
uv tool install -e .

```

--------------------------------

### Check Python Version

Source: https://voicemode.readthedocs.io/en/latest/guides/kokoro-setup

Verify that your Python installation meets the minimum requirement of Python 3.8+ for Kokoro.

```bash
python3 --version
```

--------------------------------

### Minimal Setup: Voice Only

Source: https://voicemode.readthedocs.io/en/latest/guides/selective-tool-loading

Configure VoiceMode to load only the 'converse' tool for basic voice conversations with minimal token usage.

```bash
export VOICEMODE_TOOLS_ENABLED=converse
```

--------------------------------

### Run OpenAI-Compatible Whisper Server

Source: https://voicemode.readthedocs.io/en/latest/guides/whisper-setup

Start the Whisper server with specified model, host, port, inference path, threads, and processors. The `--convert` flag is required for VoiceMode.

```bash
whisper-server \
  --model models/ggml-large-v2.bin \
  --host 127.0.0.1 \
  --port 2022 \
  --inference-path "/v1/audio/transcriptions" \
  --threads 4 \
  --processors 1 \
  --convert \
  --print-progress

```

--------------------------------

### Incorrect Permissions Syntax Example

Source: https://voicemode.readthedocs.io/en/latest/guides/permissions

Demonstrates an incorrect JSON structure for tool permissions, highlighting the need for the `permissions.allow` format.

```json
{
  "allowedTools": ["mcp__voicemode__converse"]
}

```

--------------------------------

### Manage Kokoro Service on Linux

Source: https://voicemode.readthedocs.io/en/latest/guides/kokoro-setup

Commands to start, stop, enable, disable, and check the status/logs of the Kokoro service using `systemctl` on Linux.

```bash
# Start/stop service
systemctl --user start kokoro
systemctl --user stop kokoro

# Enable/disable at startup
systemctl --user enable kokoro
systemctl --user disable kokoro

# Check status and logs
systemctl --user status kokoro
journalctl --user -u kokoro -f

```

--------------------------------

### Start MCP Server with HTTP Transport

Source: https://voicemode.readthedocs.io/en/latest/reference/cli

Starts the MCP server with HTTP transport for remote access. Allows customization of host, port, transport protocol, logging level, and access control.

```bash
voicemode serve [OPTIONS]

```

```bash
# Local development with streamable-http (default - localhost only)
voicemode serve

```

```bash
# Explicitly specify streamable-http transport
voicemode serve --transport streamable-http

```

```bash
# Use SSE transport (deprecated - for legacy compatibility)
voicemode serve --transport sse

```

```bash
# Allow Anthropic's Claude.ai and Claude Cowork to connect
voicemode serve --allow-anthropic

```

```bash
# Custom IP allowlist
voicemode serve --allow-ip 192.168.1.0/24 --allow-ip 10.0.0.0/8

```

```bash
# Allow all devices on your Tailscale network
voicemode serve --allow-tailscale

```

```bash
# Strict Anthropic-only mode (no localhost)
voicemode serve --allow-anthropic --no-allow-local

```

```bash
# URL secret authentication (recommended for Claude.ai)
voicemode serve --secret my-secret-uuid

```

```bash
# Bearer token authentication
voicemode serve --token my-secret-token

```

```bash
# Defense in depth: combine IP allowlist + token
voicemode serve --allow-anthropic --token my-secret-token

```

```bash
# SSE with secret path segment (deprecated)
voicemode serve --transport sse --secret my-secret-uuid

```

```bash
# Enable debug logging for troubleshooting
voicemode serve --log-level debug

```

--------------------------------

### serve command

Source: https://voicemode.readthedocs.io/en/latest/reference/cli

Starts the MCP server with HTTP transport for remote access, offering various configuration options for host, port, transport protocol, logging, and access control.

```APIDOC
## Core Commands

### serve

Start the MCP server with HTTP transport for remote access

```
voicemode serve [OPTIONS]

Options:
  --host TEXT                  Host to bind to (default: 127.0.0.1)
  -p, --port INTEGER           Port to bind to (default: 8765)
  --transport, -t [streamable-http|sse]
                               Transport protocol to use (default: streamable-http)
  --log-level [debug|info|warning|error]
                               Logging level (default: info)
  --allow-anthropic / --no-allow-anthropic
                               Allow Anthropic IP ranges (160.79.104.0/21)
  --allow-tailscale / --no-allow-tailscale
                               Allow Tailscale IP range (100.64.0.0/10)
  --allow-ip CIDR              Add custom CIDR to allowlist (repeatable)
  --allow-local / --no-allow-local
                               Allow localhost connections (default: true)
  --secret SECRET              Require secret path segment for access
  --token TOKEN                Require Bearer token authentication

Examples:
# Local development with streamable-http (default - localhost only)
voicemode serve

# Explicitly specify streamable-http transport
voicemode serve --transport streamable-http

# Use SSE transport (deprecated - for legacy compatibility)
voicemode serve --transport sse

# Allow Anthropic's Claude.ai and Claude Cowork to connect
voicemode serve --allow-anthropic

# Custom IP allowlist
voicemode serve --allow-ip 192.168.1.0/24 --allow-ip 10.0.0.0/8

# Allow all devices on your Tailscale network
voicemode serve --allow-tailscale

# Strict Anthropic-only mode (no localhost)
voicemode serve --allow-anthropic --no-allow-local

# URL secret authentication (recommended for Claude.ai)
voicemode serve --secret my-secret-uuid

# Bearer token authentication
voicemode serve --token my-secret-token

# Defense in depth: combine IP allowlist + token
voicemode serve --allow-anthropic --token my-secret-token

# SSE with secret path segment (deprecated)
voicemode serve --transport sse --secret my-secret-uuid

# Enable debug logging for troubleshooting
voicemode serve --log-level debug
```
```

--------------------------------

### Install VoiceMode System Dependencies on Ubuntu/Debian

Source: https://voicemode.readthedocs.io/en/latest

Installs necessary system packages for VoiceMode on Ubuntu and Debian-based systems, including ffmpeg, build tools, and audio libraries. Pulseaudio packages are specifically noted as required for microphone access on WSL2.

```bash
sudo apt update
sudo apt install -y ffmpeg gcc libasound2-dev libasound2-plugins libportaudio2 portaudio19-dev pulseaudio pulseaudio-utils python3-dev
```

--------------------------------

### Serve VoiceMode with Token Authentication

Source: https://voicemode.readthedocs.io/en/latest/guides/serve-configuration

Starts the VoiceMode server, allowing connections from any IP but requiring a token for authentication. Suitable for API clients.

```bash
voicemode serve --allow-anthropic --token your-secret-token
```

--------------------------------

### VoiceMode Service Management Commands

Source: https://voicemode.readthedocs.io/en/latest/guides/configuration

Commands to start, enable auto-start, and check the status of the VoiceMode HTTP server service.

```bash
# Start VoiceMode HTTP server
voicemode service start voicemode

# Enable auto-start at boot/login
voicemode service enable voicemode

# Check status
voicemode service status voicemode
```

--------------------------------

### Install VoiceMode on NixOS using Development Shell

Source: https://voicemode.readthedocs.io/en/latest

Uses a Nix development shell to set up VoiceMode on NixOS, providing an isolated environment for development or usage.

```bash
# Use development shell
nix develop github:mbailey/voicemode
```

--------------------------------

### Serve VoiceMode with Environment Variable Token

Source: https://voicemode.readthedocs.io/en/latest/guides/serve-configuration

Starts the VoiceMode server using a token stored in an environment variable for enhanced security and scriptability.

```bash
# Use environment variable
export VOICEMODE_TOKEN="your-secret-token"
voicemode serve --allow-anthropic --token "$VOICEMODE_TOKEN"
```

--------------------------------

### Serve VoiceMode with Secret Authentication

Source: https://voicemode.readthedocs.io/en/latest/guides/serve-configuration

Starts the VoiceMode server, allowing connections from any IP but requiring a URL-embedded secret for authentication. Best for Claude.ai.

```bash
voicemode serve --allow-anthropic --secret your-secret-uuid
```

--------------------------------

### Manage LiveKit RTC Service

Source: https://voicemode.readthedocs.io/en/latest/reference/cli

Commands for installing, uninstalling, starting, stopping, restarting, and managing the status of the LiveKit RTC service. Includes options for updating service files and viewing logs.

```bash
voicemode livekit install
```

```bash
voicemode livekit uninstall --remove-all-data
```

```bash
voicemode livekit start
```

```bash
voicemode livekit stop
```

```bash
voicemode livekit restart
```

```bash
voicemode livekit status
```

```bash
voicemode livekit enable
```

```bash
voicemode livekit disable
```

```bash
voicemode livekit update
```

```bash
voicemode livekit logs --follow
```

--------------------------------

### Makefile Commands for Development

Source: https://voicemode.readthedocs.io/en/latest/tutorials/development-setup

Common development tasks managed via Makefile, including installation, testing, linting, formatting, building, and service management.

```makefile
# Development
make dev           # Install in dev mode
make test         # Run tests
make lint         # Run linters
make format       # Format code

# Building
make build        # Build package
make clean        # Clean build artifacts

# Services
make install-services  # Install local services
make start-services   # Start local services
make stop-services    # Stop local services

# Documentation
make docs         # Build documentation
make docs-serve   # Serve docs locally
```

--------------------------------

### Manage Whisper STT Service

Source: https://voicemode.readthedocs.io/en/latest/reference/cli

Commands for installing, uninstalling, starting, stopping, restarting, and managing the status of the Whisper STT service. Also includes options for managing models and viewing logs.

```bash
voicemode whisper install --model medium.en
```

```bash
voicemode whisper uninstall
```

```bash
voicemode whisper start
```

```bash
voicemode whisper stop
```

```bash
voicemode whisper restart
```

```bash
voicemode whisper status
```

```bash
voicemode whisper enable
```

```bash
voicemode whisper disable
```

```bash
voicemode whisper models
```

```bash
voicemode whisper model active
```

```bash
voicemode whisper model active large-v3
```

```bash
voicemode whisper model install large-v2
```

```bash
voicemode whisper model remove tiny.en
```

```bash
voicemode whisper logs --follow
```

--------------------------------

### Multi-Agent Voice Focus Configuration

Source: https://voicemode.readthedocs.io/en/latest/guides/configuration

Configure automatic tmux pane focus for multi-agent voice setups. When an agent starts speaking, its pane can be brought into focus, respecting existing focus-hold settings.

```dotenv
# Auto-focus tmux pane when an agent starts speaking (default: false)
# Switches tmux focus to the speaking agent's pane *after* conch acquisition,
# so agents waiting on the conch never steal focus. Respects the focus-hold
# sentinel written by show-me (~/.voicemode/focus-hold) so a shown file is
# not yanked away. Silent no-op outside tmux.
VOICEMODE_AUTO_FOCUS_PANE=false

```

--------------------------------

### Configure Preferred Voices in .voicemode.env

Source: https://voicemode.readthedocs.io/en/latest/guides/selecting-voices

Set your preferred TTS voices in the `.voicemode.env` file. This example prioritizes Kokoro voices, falling back to OpenAI.

```shell
# Try Kokoro first, fallback to OpenAI
VOICEMODE_VOICES=af_sky,nova,alloy

```

--------------------------------

### Create Settings File via Command Line

Source: https://voicemode.readthedocs.io/en/latest/guides/permissions

This command creates the `~/.claude` directory if it doesn't exist and then uses a heredoc to populate `settings.json` with VoiceMode permissions.

```bash
# Create settings file with VoiceMode permissions
mkdir -p ~/.claude
cat > ~/.claude/settings.json << 'EOF'
{
  "permissions": {
    "allow": [
      "mcp__voicemode__converse",
      "mcp__voicemode__service"
    ]
  }
}
EOF

```

--------------------------------

### Serve VoiceMode with Streamable HTTP Transport

Source: https://voicemode.readthedocs.io/en/latest/guides/serve-configuration

Starts the VoiceMode server using the default and recommended streamable HTTP transport, exposing the MCP endpoint.

```bash
voicemode serve --transport streamable-http
# Endpoint: http://127.0.0.1:8765/mcp
```

--------------------------------

### Manually Run Kokoro FastAPI Server

Source: https://voicemode.readthedocs.io/en/latest/guides/kokoro-setup

Manually start the Kokoro FastAPI server using uvx, specifying host, port, and the directory for models. Models are downloaded automatically on first use.

```bash
# Create models directory
mkdir -p ~/Models/kokoro

# Run kokoro-fastapi with uvx
uvx kokoro-fastapi[cpu] serve \
  --host 127.0.0.1 \
  --port 8880 \
  --models-dir ~/Models/kokoro

```

--------------------------------

### Serve VoiceMode with Anthropic IP Allowlist

Source: https://voicemode.readthedocs.io/en/latest/guides/serve-configuration

Starts the VoiceMode server, allowing connections originating from Anthropic's IP ranges and using a secret for authentication.

```bash
# Allow Anthropic's outbound IPs
voicemode serve --allow-anthropic --secret your-secret-uuid
```

--------------------------------

### Hybrid Cloud and Local Voice Setup

Source: https://voicemode.readthedocs.io/en/latest/guides/configuration

Configure VoiceMode to use local services primarily, with cloud services as a fallback. Ensure your OpenAI API key is set for the fallback.

```bash
# Use local services with cloud fallback
export OPENAI_API_KEY="your-api-key"  # Fallback
# Local services auto-detected when running

```

--------------------------------

### Start Voice Conversation

Source: https://voicemode.readthedocs.io/en/latest/guides/claude-code-plugin

Initiate a voice conversation with Claude. You can start with a greeting or simply begin listening.

```bash
# Start with a greeting
/voicemode:converse Hello, how can I help you today?
```

```bash
# Just start listening
/voicemode:converse
```

--------------------------------

### Basic Word Replacement Example

Source: https://voicemode.readthedocs.io/en/latest/guides/pronunciation

Example of a TTS rule to replace 'Tali' with its phonetic pronunciation 'Tar-lee'.

```shell
# Replace "Tali" with phonetic pronunciation
TTS Tali Tar-lee # Dog's name
```

--------------------------------

### Create and Switch Custom Soundfont Pack

Source: https://voicemode.readthedocs.io/en/latest/guides/soundfonts

Create a new soundfont pack by copying the default, replacing sounds, and then switching to it by creating a symbolic link.

```bash
cp -r ~/.voicemode/soundfonts/voicemode ~/.voicemode/soundfonts/my-pack

```

```bash
ln -sfn my-pack ~/.voicemode/soundfonts/current

```

--------------------------------

### Configure VoiceMode with Environment Variables

Source: https://voicemode.readthedocs.io/en/latest/reference/cli

Demonstrates how to use environment variables to configure VoiceMode, such as setting an API key, enabling debug mode, or specifying local service URLs.

```bash
# Use specific API key
OPENAI_API_KEY=sk-... voicemode converse
```

```bash
# Enable debug mode
VOICEMODE_DEBUG=true voicemode
```

```bash
# Use local services
VOICEMODE_TTS_BASE_URLS=http://localhost:8880/v1 voicemode converse
```

--------------------------------

### Initialize FastMCP Server

Source: https://voicemode.readthedocs.io/en/latest/reference/tool-loading-architecture

Initializes the FastMCP server, automatically discovering decorated tools from the voice_mode.tools directory upon import.

```python
# Tools are auto-imported from the tools directory
import voice_mode.tools

# FastMCP server automatically discovers decorated tools
mcp = fastmcp.FastMCP(
    name="voicemode",
    version=__version__
)

```

--------------------------------

### Install VoiceMode on NixOS System-Wide

Source: https://voicemode.readthedocs.io/en/latest

Installs VoiceMode system-wide on NixOS by adding it to the system configuration. This makes the VoiceMode package available globally.

```nix
# In /etc/nixos/configuration.nix
environment.systemPackages = [
  (builtins.getFlake "github:mbailey/voicemode").packages.${pkgs.system}.default
];
```

--------------------------------

### Install VoiceMode System Dependencies on macOS

Source: https://voicemode.readthedocs.io/en/latest

Installs necessary dependencies for VoiceMode on macOS using Homebrew, including ffmpeg, Node.js, and portaudio.

```bash
brew install ffmpeg node portaudio
```

--------------------------------

### Verify Settings File Content

Source: https://voicemode.readthedocs.io/en/latest/guides/permissions

Use the `cat` command to display the contents of your `~/.claude/settings.json` file to verify the applied permissions.

```bash
cat ~/.claude/settings.json

```

--------------------------------

### Enable Auto-Start for Local Services

Source: https://voicemode.readthedocs.io/en/latest/tutorials/getting-started

Configures local voice services (Whisper, Kokoro) to start automatically at login or boot. This uses system-specific mechanisms like launchd agents or systemd user services.

```bash
# Enable services to start at boot/login
voicemode service enable whisper
voicemode service enable kokoro

```

--------------------------------

### Privacy-Focused Local Setup Configuration

Source: https://voicemode.readthedocs.io/en/latest/guides/configuration

Configure VoiceMode for a privacy-focused local setup by specifying local URLs for TTS and STT services, and setting a local voice.

```env
# No cloud services, everything local
export VOICEMODE_TTS_BASE_URLS=http://127.0.0.1:8880/v1
export VOICEMODE_STT_BASE_URLS=http://127.0.0.1:2022/v1
export VOICEMODE_VOICES=af_sky
```

--------------------------------

### Health Check Examples

Source: https://voicemode.readthedocs.io/en/latest/reference/cli/service-commands

Examples of checking the health of Kokoro and Whisper services. The first shows a healthy response, while the second indicates Whisper is not responding on its designated port.

```bash
$ voicemode kokoro health
✅ Kokoro is responding
   Status: healthy
   Uptime: 2h 15m 30s

$ voicemode whisper health
❌ Whisper not responding on port 2022
```

--------------------------------

### List Available Tools

Source: https://voicemode.readthedocs.io/en/latest/reference/tool-loading-architecture

Command to list all tools currently loaded and available in the Voice Mode application.

```bash
# List all available tools
voicemode list-tools

```

--------------------------------

### Check Registry and Providers

Source: https://voicemode.readthedocs.io/en/latest/reference/cli

Inspects the VoiceMode registry and available providers.

```bash
# Check registry and providers
voicemode diag registry
```

--------------------------------

### Install VoiceMode via Python Package

Source: https://voicemode.readthedocs.io/en/latest

This option installs dependencies and the VoiceMode Python package using the UV package manager. It also shows how to add VoiceMode to Claude Code and optionally set an OpenAI API key.

```bash
# 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 voice-mode

# Optional: Add OpenAI API key as fallback for local services
export OPENAI_API_KEY=your-openai-key

# Start a conversation
claude converse
```

--------------------------------

### Project Structure Overview

Source: https://voicemode.readthedocs.io/en/latest/tutorials/development-setup

Illustrates the directory structure of the VoiceMode project, highlighting key components like the main package, tests, documentation, and frontend.

```tree
voicemode/
├── voice_mode/           # Main package
│   ├── __init__.py
│   ├── server.py         # MCP server
│   ├── cli.py           # CLI commands
│   ├── config.py        # Configuration
│   ├── tools/           # MCP tools
│   │   ├── converse.py
│   │   └── services/    # Service installers
│   ├── providers.py     # Service providers
│   ├── frontend/        # Next.js frontend
│   └── templates/       # Service templates
├── tests/               # Test suite
├── docs/               # Documentation
├── scripts/            # Development scripts
├── Makefile           # Development tasks
└── pyproject.toml     # Project configuration
```

--------------------------------

### LiveKit Server and Room Configuration

Source: https://voicemode.readthedocs.io/en/latest/guides/configuration

Configure LiveKit integration, including the server URL and port, and settings for automatically creating VoiceMode rooms.

```env
# Server settings
LIVEKIT_URL=ws://127.0.0.1:7880
LIVEKIT_PORT=7880

# Room settings
VOICEMODE_LIVEKIT_ROOM_PREFIX=voicemode
VOICEMODE_LIVEKIT_AUTO_CREATE=true
```

--------------------------------

### Add Plugin Marketplace

Source: https://voicemode.readthedocs.io/en/latest/guides/claude-code-plugin

Add the VoiceMode plugin marketplace to Claude Code. This is a prerequisite for installing the plugin.

```bash
# Add the marketplace
claude plugin marketplace add https://github.com/mbailey/claude-plugins
```

--------------------------------

### Configure Local Setup for STT and TTS

Source: https://voicemode.readthedocs.io/en/latest/guides/whisper-setup

Set environment variables for Whisper STT and Kokoro TTS base URLs, and specify the Kokoro TTS voice for fully offline voice processing.

```bash
export STT_BASE_URL=http://127.0.0.1:2022/v1  # Whisper for STT
export TTS_BASE_URL=http://127.0.0.1:8880/v1  # Kokoro for TTS
export TTS_VOICE=af_sky                       # Kokoro voice

```

--------------------------------

### Technical Acronym Pronunciation

Source: https://voicemode.readthedocs.io/en/latest/guides/pronunciation

Examples of TTS rules for technical acronyms like 'PoE', 'TCP/IP', and 'SSH'.

```shell
# Networking terms
TTS PoE "P O E" # Power over Ethernet
TTS TCP/IP "T C P I P" # Protocol
TTS SSH "S S H" # Secure Shell
```

--------------------------------

### Generate Shell Completion Scripts

Source: https://voicemode.readthedocs.io/en/latest/reference/cli

Commands to install or generate shell completion scripts for bash, zsh, or fish.

```bash
# Install completions for your shell
voicemode completions install
```

```bash
# Generate completion script for specific shell
voicemode completions bash
```

```bash
voicemode completions zsh
```

```bash
voicemode completions fish
```

--------------------------------

### Configure Kokoro Environment Variables

Source: https://voicemode.readthedocs.io/en/latest/guides/kokoro-setup

Set environment variables in `~/.voicemode/voicemode.env` to configure Kokoro's port, model directory, cache directory, and default voice.

```bash
VOICEMODE_KOKORO_PORT=8880
VOICEMODE_KOKORO_MODELS_DIR=~/Models/kokoro
VOICEMODE_KOKORO_CACHE_DIR=~/.voicemode/cache/kokoro
VOICEMODE_KOKORO_DEFAULT_VOICE=af_sky

```

--------------------------------

### Environment Variable Configuration

Source: https://voicemode.readthedocs.io/en/latest/guides/selective-tool-loading

Configure tool loading by setting the VOICEMODE_TOOLS_ENABLED environment variable before starting Claude Code.

```bash
export VOICEMODE_TOOLS_ENABLED=converse,service
claude  # Start Claude Code
```

--------------------------------

### Manual Testing Commands

Source: https://voicemode.readthedocs.io/en/latest/tutorials/development-setup

Commands for manual testing, including starting a debug conversation or testing with custom provider URLs.

```bash
# Test voice conversation
voicemode converse --debug

# Test with different providers
VOICEMODE_TTS_BASE_URLS=http://localhost:8880/v1 voicemode converse
```

--------------------------------

### Edit Settings File with Nano

Source: https://voicemode.readthedocs.io/en/latest/guides/permissions

Use the nano editor to create or modify the `~/.claude/settings.json` file to apply permissions.

```bash
# Create or edit the file
nano ~/.claude/settings.json

```

--------------------------------

### Common Use Case: Technical Terms

Source: https://voicemode.readthedocs.io/en/latest/guides/pronunciation

Examples of TTS rules for technical terms and acronyms such as 'PoE+', 'GbE', and 'NVMe'.

```shell
TTS PoE+ "P O E plus" # PoE+
TTS GbE "gigabit ethernet"
TTS NVMe "N V M E"
```

--------------------------------

### Run Unit and Integration Tests

Source: https://voicemode.readthedocs.io/en/latest/tutorials/development-setup

Executes unit tests in the 'tests/unit/' directory or integration tests in 'tests/integration/'. Supports running tests with markers.

```bash
# Run all unit tests
pytest tests/unit/

# Run with markers
pytest -m "not integration"

# Run integration tests
pytest tests/integration/

# Run specific service tests
pytest tests/integration/test_whisper.py
```

--------------------------------

### STT Corrections for Misrecognitions

Source: https://voicemode.readthedocs.io/en/latest/guides/pronunciation

Examples of STT rules to correct common misrecognitions by Whisper, including phonetic variations and capitalization.

```shell
# Fix common Whisper misrecognitions
STT "me tool" metool # Whisper hears this wrong
STT "cora 7" "Cora 7" # Fix capitalization
STT "(tally|tahlee|tolly)" Tali # Multiple variations
```

--------------------------------

### Company/Brand Name Pronunciation

Source: https://voicemode.readthedocs.io/en/latest/guides/pronunciation

Examples of TTS rules for company names like '3M' and 'AWS' to ensure correct pronunciation.

```shell
# 3M company name
TTS 3M "three M" # Avoid "3 million"

# AWS
TTS AWS "A W S" # Amazon Web Services
```