# Voice Mode Installation Tools

> Voice Mode now includes MCP tools to automatically install and configure whisper.cpp and kokoro-fastapi, making it easier to set up free, private, open-source voice services.

- Skill: `tools-only/voice-mode-installation-tools` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add tools-only/voice-mode-installation-tools`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/voice-mode-installation-tools/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tools-only (https://skillmd.com/u/tools-only)
- Updated: 2026-09-29
- Page: https://skillmd.com/skills/tools-only/voice-mode-installation-tools

---

# Voice Mode Installation Tools

Voice Mode now includes MCP tools to automatically install and configure whisper.cpp and kokoro-fastapi, making it easier to set up free, private, open-source voice services.

## Overview

These tools handle:
- System detection (macOS/Linux)
- Dependency installation
- GPU support configuration
- Model downloads
- Service configuration

## Available Tools

### install_whisper_cpp

Installs [whisper.cpp](https://github.com/ggerganov/whisper.cpp) for speech-to-text (STT) functionality.

#### Features
- Automatic OS detection (macOS/Linux)
- GPU acceleration (Metal on macOS, CUDA on Linux)
- Model download management
- Build optimization
- Service configuration (launchd on macOS, systemd on Linux)
- Environment variable support for model selection

#### Usage

```python
# Basic installation with defaults
result = await install_whisper_cpp()

# Custom installation
result = await install_whisper_cpp(
    install_dir="~/my-whisper",
    model="large-v3",
    use_gpu=True,
    force_reinstall=False
)
```

#### Parameters
- `install_dir` (str, optional): Installation directory (default: `~/.voicemode/whisper.cpp`)
- `model` (str, optional): Whisper model to download (default: `large-v2`)
  - Available models: `tiny`, `tiny.en`, `base`, `base.en`, `small`, `small.en`, `medium`, `medium.en`, `large-v2`, `large-v3`
  - Note: large-v2 is default for best accuracy (requires ~3GB RAM)
- `use_gpu` (bool, optional): Enable GPU support (default: auto-detect)
- `force_reinstall` (bool, optional): Force reinstallation (default: false)

#### Return Value
```python
{
    "success": True,
    "install_path": "/Users/user/.voicemode/whisper.cpp",
    "model_path": "/Users/user/.voicemode/whisper.cpp/models/ggml-large-v2.bin",
    "gpu_enabled": True,
    "gpu_type": "metal",  # or "cuda" or "cpu"
    "performance_info": {
        "system": "Darwin",
        "gpu_acceleration": "metal",
        "model": "large-v2",
        "binary_path": "/Users/user/.voicemode/whisper.cpp/main",
        "server_port": 2022,
        "server_url": "http://localhost:2022"
    },
    "launchagent": "/Users/user/Library/LaunchAgents/com.voicemode.whisper-server.plist",  # macOS
    "systemd_service": "/home/user/.config/systemd/user/whisper-server.service",  # Linux
    "start_script": "/Users/user/.voicemode/whisper.cpp/start-whisper-server.sh"
}
```

### install_kokoro_fastapi

Installs [kokoro-fastapi](https://github.com/remsky/kokoro-fastapi) for text-to-speech (TTS) functionality.

#### Features
- Python environment management with UV
- Automatic model downloads
- Service configuration (launchd on macOS, systemd on Linux)
- Auto-start capability

#### Usage

```python
# Basic installation with defaults
result = await install_kokoro_fastapi()

# Custom installation
result = await install_kokoro_fastapi(
    install_dir="~/my-kokoro",
    models_dir="~/my-models",
    port=8881,
    auto_start=True,
    install_models=True,
    force_reinstall=False
)
```

#### Parameters
- `install_dir` (str, optional): Installation directory (default: `~/.voicemode/kokoro-fastapi`)
- `models_dir` (str, optional): Models directory (default: `~/.voicemode/kokoro-models`)
- `port` (int, optional): Service port (default: 8880)
- `auto_start` (bool, optional): Start service after installation (default: true)
- `install_models` (bool, optional): Download Kokoro models (default: true)
- `force_reinstall` (bool, optional): Force reinstallation (default: false)

#### Return Value
```python
{
    "success": True,
    "install_path": "/home/user/.voicemode/kokoro-fastapi",
    "service_url": "http://127.0.0.1:8880",
    "service_status": "managed_by_systemd",  # Linux
    "service_status": "managed_by_launchd",  # macOS
    "systemd_service": "/home/user/.config/systemd/user/kokoro-fastapi-8880.service",  # Linux
    "launchagent": "/Users/user/Library/LaunchAgents/com.voicemode.kokoro-8880.plist",  # macOS
    "start_script": "/home/user/.voicemode/kokoro-fastapi/start-cpu.sh",
    "message": "Kokoro-fastapi installed. Run: cd /home/user/.voicemode/kokoro-fastapi && ./start-cpu.sh"
}
```

## System Requirements

### whisper.cpp

#### macOS
- Xcode Command Line Tools
- Homebrew (for cmake)
- Metal support (built-in)

#### Linux
- Build essentials (gcc, g++, make)
- CMake
- CUDA toolkit (optional, for NVIDIA GPU support)

### kokoro-fastapi

#### All Systems
- Python 3.10+
- Git
- ~5GB disk space for models
- UV package manager (installed automatically if missing)

## Integration with Voice Mode

After installation, the services integrate automatically with Voice Mode:

1. **whisper.cpp**: 
   - Runs automatically on boot (port 2022)
   - OpenAI-compatible API endpoint
   - Model selection via `VOICEMODE_WHISPER_MODEL` environment variable
   - View installed models: `claude resource read whisper://models`

2. **kokoro-fastapi**: 
   - Automatically detected by Voice Mode's provider registry when running
   - 67 voices available
   - OpenAI-compatible API endpoint

## Examples

### Complete Setup

```python
# Install both services with defaults
whisper_result = await install_whisper_cpp()  # Uses large-v2 by default
kokoro_result = await install_kokoro_fastapi()

# Check installation status
if whisper_result["success"] and kokoro_result["success"]:
    print("Voice services installed successfully!")
    print(f"Whisper: {whisper_result['install_path']}")
    print(f"Whisper server: {whisper_result['performance_info']['server_url']}")
    print(f"Kokoro API: {kokoro_result['service_url']}")
```

### Upgrade Existing Installation

```python
# Force reinstall with larger model
result = await install_whisper_cpp(
    model="large-v3",
    force_reinstall=True
)
```

### Custom Configuration

```python
# Install kokoro-fastapi on different port
result = await install_kokoro_fastapi(
    port=9000,
    models_dir="/opt/models/kokoro"
)
```

## Troubleshooting

### Common Issues

1. **Missing Dependencies**
   - The tools will report missing dependencies with installation instructions
   - Follow the provided commands to install required packages

2. **Port Conflicts**
   - If port 8880 is in use, specify a different port for kokoro-fastapi
   - Check running services: `lsof -i :8880`

3. **GPU Not Detected**
   - On Linux, ensure NVIDIA drivers and CUDA are installed
   - Use `nvidia-smi` to verify GPU availability
   - Force CPU mode with `use_gpu=False` if needed

4. **Model Download Failures**
   - Check internet connection
   - Verify sufficient disk space
   - Try smaller models first (tiny, base)

### Manual Service Management

#### macOS (launchd)
```bash
# Whisper
launchctl load ~/Library/LaunchAgents/com.voicemode.whisper-server.plist
launchctl unload ~/Library/LaunchAgents/com.voicemode.whisper-server.plist

# Kokoro
launchctl load ~/Library/LaunchAgents/com.voicemode.kokoro.plist
launchctl unload ~/Library/LaunchAgents/com.voicemode.kokoro.plist
```

#### Linux (systemd)
```bash
# Whisper
systemctl --user start whisper-server
systemctl --user stop whisper-server
systemctl --user status whisper-server

# Kokoro
systemctl --user start kokoro-fastapi-8880
systemctl --user stop kokoro-fastapi-8880
systemctl --user status kokoro-fastapi-8880
```

#### Change Whisper Model
```bash
# Set environment variable before restarting
export VOICEMODE_WHISPER_MODEL=base.en  # or tiny, small, medium, large-v2, large-v3

# Restart service to apply change
# macOS
launchctl unload ~/Library/LaunchAgents/com.voicemode.whisper-server.plist
launchctl load ~/Library/LaunchAgents/com.voicemode.whisper-server.plist

# Linux
systemctl --user restart whisper-server
```

## Testing

Run the test suite to verify installation tools:

```bash
cd /path/to/voicemode
python -m pytest tests/test_installers.py -v

# Skip integration tests (no actual installation)
SKIP_INTEGRATION_TESTS=1 python -m pytest tests/test_installers.py -v
```

## Contributing

When adding new installation tools:

1. Create a new function in `voice_mode/tools/installers.py`
2. Use the `@mcp.tool()` decorator
3. Follow the existing pattern for error handling and return values
4. Add comprehensive tests in `tests/test_installers.py`
5. Update this documentation

## Security Notes

- All installations are performed in user space (no sudo required)
- Models are downloaded from official sources
- Services bind to localhost only by default
- No external network access without explicit configuration