Development Setup¶

Note: These docs need review.

This guide covers setting up VoiceMode for development, including building from source, configuring your IDE, and contributing to the project.

Prerequisites¶

Python 3.10 or higher
Git
UV package manager (recommended) or pip
Node.js 18+ (for frontend development)

Setting Up UV¶

UV is a fast Python package manager written in Rust. It's the recommended tool for VoiceMode development:

# Install UV
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or using pip
pip install uv

Cloning the Repository¶

# Clone the repository
git clone https://github.com/mbailey/voicemode
cd voicemode

# Install in development mode
uv tool install -e .

Development Workflow¶

Running from Source¶

Building the Package¶

# Build the package
uv build

# This creates:
# dist/voice_mode-X.Y.Z-py3-none-any.whl
# dist/voice_mode-X.Y.Z.tar.gz

# Test the built package
uvx --from dist/voice_mode-*.whl voice-mode

Running Tests¶

# Run all tests
pytest

# Run with coverage
pytest --cov=voice_mode

# Run specific test file
pytest tests/test_converse.py

# Run with verbose output
pytest -v

Using Local Services¶

For development without API keys:

# Or manually
voicemode whisper install
voicemode kokoro install

# Or manually
voicemode whisper start
voicemode kokoro start

Project Structure¶

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

Common Development Tasks¶

Adding a New Tool¶

Create tool file in voice_mode/tools/
Implement tool class with MCP decorators
Add tests in tests/tools/
Update documentation

Modifying Configuration¶

Update voice_mode/config.py
Add environment variable to docs
Update tests for new config
Add to example .env files

Updating Dependencies¶

# Add a new dependency
uv add requests

# Add development dependency
uv add --dev pytest-mock

# Update all dependencies
uv sync

Debugging¶

Enable Debug Mode¶

export VOICEMODE_DEBUG=true
export VOICEMODE_LOG_LEVEL=debug

Debug Output Locations¶

Logs: ~/.voicemode/logs/
Audio files: ~/.voicemode/debug/
Event logs: ~/.voicemode/events.log

Common Debug Commands¶

# Check service status
voicemode whisper status
voicemode kokoro status

Testing¶

Unit Tests¶

# Run all unit tests
pytest tests/unit/

# Run with markers
pytest -m "not integration"

Integration Tests¶

# Run integration tests
pytest tests/integration/

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

Manual Testing¶

# Test voice conversation
voice-mode converse --debug

# Test specific tool
voice-mode test-tool converse

# Test with different providers
VOICEMODE_TTS_BASE_URLS=http://localhost:8880/v1 voice-mode converse

Contributing¶

Code Style¶

We use Black for formatting and Ruff for linting:

# Format code
black voice_mode tests

# Run linter
ruff check voice_mode tests

# Fix linting issues
ruff check --fix voice_mode tests

Pre-commit Hooks¶

# Install pre-commit
pip install pre-commit

# Install hooks
pre-commit install

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

Commit Messages¶

Follow conventional commits: - feat: New feature - fix: Bug fix - docs: Documentation - test: Tests - refactor: Code refactoring - chore: Maintenance

Pull Request Process¶

Fork the repository
Create feature branch
Make changes with tests
Run test suite
Submit pull request

Makefile Commands¶

# 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

Troubleshooting Development Issues¶

Import Errors¶

uv pip install -e .

Service Connection Issues¶

# Check if ports are in use
lsof -i :8880  # Kokoro
lsof -i :2022  # Whisper
lsof -i :7880  # LiveKit

# Kill stuck processes
pkill -f kokoro
pkill -f whisper