# Building Voice Mode

> This guide covers building Voice Mode for local development and testing.

- Skill: `tools-only/building-voice-mode` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add tools-only/building-voice-mode`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/building-voice-mode/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/building-voice-mode

---

# Building Voice Mode

This guide covers building Voice Mode for local development and testing.

## Prerequisites

- Python >= 3.10
- [uv](https://github.com/astral-sh/uv) installed

Note: Development builds temporarily modify the version file, but `make build-dev` automatically restores it.

## Building a Development Version

### Automatic Dev Versioning (Recommended)

Use the `make build-dev` command for automatic versioning:

```bash
# Automatically appends .dev + timestamp to current version
make build-dev
```

This creates a unique development version like `2.4.2.dev20240627123456`.

The command safely handles version updates with automatic rollback on errors.

### Manual Version Update

If you prefer to set a specific dev version:

```bash
# Edit voice_mode/__version__.py
__version__ = "2.4.2.dev0"  # Example dev version

# Then build
uv build
```

This creates wheel and source distributions in the `dist/` directory:
- `dist/voice_mode-2.4.2.dev0-py3-none-any.whl`
- `dist/voice_mode-2.4.2.dev0.tar.gz`

## Installing Your Build

### In Another Project

```bash
# Install the wheel directly
pip install /path/to/voicemode/dist/voice_mode-2.4.2.dev0-py3-none-any.whl

# Or with uv
uv pip install /path/to/voicemode/dist/voice_mode-2.4.2.dev0-py3-none-any.whl
```

### In MCP Configuration

For testing with Claude Code or other MCP clients:

```json
{
  "mcpServers": {
    "voice-mode-dev": {
      "command": "python",
      "args": ["-m", "voice_mode"],
      "env": {
        "PYTHONPATH": "/path/to/voicemode",
        "OPENAI_API_KEY": "your-key"
      }
    }
  }
}
```

## Version Management

### Development Versions

- Use `.devN` suffix: `2.4.2.dev0`, `2.4.2.dev1`, etc.
- These won't be published to PyPI by CI/CD
- Increment the dev number for each test build

### Release Versions

- Use semantic versioning: `2.4.2`, `2.5.0`, etc.
- Only create release versions when ready to publish
- Use `make release` for official releases

## Testing Your Build

1. Create a test environment:
```bash
uv venv test-env
source test-env/bin/activate  # On Windows: test-env\Scripts\activate
```

2. Install your build:
```bash
uv pip install dist/voice_mode-*.whl
```

3. Test the installation:
```bash
python -m voice_mode --help
```

## Troubleshooting

### Build Errors

- Ensure you're in the project root directory
- Check that `pyproject.toml` is valid
- Run `uv sync` to ensure dependencies are installed

### Import Errors

- Verify the wheel installed correctly: `pip show voice-mode`
- Check Python path: `python -c "import voice_mode; print(voice_mode.__file__)"`

### Version Conflicts

- Uninstall existing versions: `pip uninstall voice-mode`
- Use virtual environments to isolate installations