voice-mode-install

A standalone installer package for VoiceMode that handles system dependency detection and installation.

Overview

voice-mode-install simplifies the VoiceMode installation process by:

1. Detecting your platform - Identifies your OS, distribution, and architecture
2. Checking dependencies - Scans for required system packages
3. Installing packages - Uses your system's package manager (apt, dnf, brew)
4. Installing VoiceMode - Runs uv tool install voice-mode
5. Hardware recommendations - Suggests optimal configuration for your system
6. Logging everything - Saves installation logs for troubleshooting

Quick Start

# Install and run
uvx voice-mode-install

# Dry run (see what would be installed)
uvx voice-mode-install --dry-run

# Install specific version
uvx voice-mode-install --voice-mode-version=5.1.3

# Skip service installation
uvx voice-mode-install --skip-services

# Non-interactive mode
uvx voice-mode-install --non-interactive

Prerequisites

• uv - Required to run the installer (curl -LsSf https://astral.sh/uv/install.sh | sh)
• Python 3.10+ - Usually pre-installed on modern systems
• sudo access - Needed to install system packages (Linux)
• Homebrew (macOS) - The installer will offer to install it if missing

Supported Platforms

• macOS - Intel and Apple Silicon (via Homebrew)
• Ubuntu/Debian - Using apt package manager
• Fedora/RHEL - Using dnf package manager

Features

Phase 1 (Included)

✅ Dry-run Mode - Preview what will be installed ✅ Installation Logging - Detailed logs saved to ~/.voicemode/install.log ✅ Shell Completion - Auto-configures tab completion for bash/zsh ✅ Health Check - Verifies installation after completion ✅ Version Pinning - Install specific VoiceMode versions ✅ Hardware Detection - Recommends optimal setup for your system ✅ Homebrew Auto-Install - Offers to install Homebrew on macOS if missing

Phase 2 (Future)

⏱️ Config Validation - Check for conflicting settings ⏱️ Uninstall Support - Clean removal of VoiceMode

How It Works

1. Platform Detection - Identifies OS, distribution, and architecture
2. Dependency Checking - Compares installed packages against dependencies.yaml
3. Package Manager Setup (macOS only) - Checks for Homebrew and offers to install if missing
4. Package Installation - Uses platform-specific package managers:
   • macOS: brew install (installs Homebrew first if needed)
   • Ubuntu/Debian: sudo apt install
   • Fedora: sudo dnf install
5. VoiceMode Installation - Runs uv tool install voice-mode[==version]
6. Post-Install - Configures shell completion and verifies installation

Installation Logs

Logs are saved to ~/.voicemode/install.log in JSONL format:

{"timestamp": "2025-10-12T10:30:00", "type": "start", "message": "Installation started"}
{"timestamp": "2025-10-12T10:30:15", "type": "check", "message": "Checked core dependencies"}
{"timestamp": "2025-10-12T10:30:45", "type": "install", "message": "Successfully installed system packages"}
{"timestamp": "2025-10-12T10:31:30", "type": "complete", "message": "Installation completed"}

Troubleshooting

VoiceMode command not found after installation

Restart your shell or run:

source ~/.bashrc  # or ~/.zshrc for zsh

Permission denied during package installation

The installer needs sudo access to install system packages. Run:

sudo -v  # Refresh sudo credentials
uvx voice-mode-install

Network errors during installation

• Check your internet connection
• Try again with: uvx voice-mode-install
• Use uvx --refresh voice-mode-install to get the latest installer

Installation hangs or fails

1. Check the log file: ~/.voicemode/install.log
2. Try a dry run: uvx voice-mode-install --dry-run
3. Report issues with log file attached

Development

Building from Source

cd installer/
uv build

Testing Locally

cd installer/
uv pip install -e .
voice-mode-install --dry-run

Project Structure

installer/
├── pyproject.toml          # Package definition
├── voicemode_install/
│   ├── __init__.py        # Version and exports
│   ├── cli.py             # Main CLI entry point
│   ├── system.py          # Platform detection
│   ├── checker.py         # Dependency checking
│   ├── installer.py       # Package installation
│   ├── hardware.py        # Hardware detection
│   ├── logger.py          # Installation logging
│   └── dependencies.yaml  # System dependencies
└── README.md

Design Decisions

See DECISIONS.md in the task directory for detailed rationale behind:

• Version management strategy
• Dependency synchronization approach
• Error handling philosophy
• Platform coverage priorities
• Service installation scope

Contributing

This installer is part of the VoiceMode project.

License

MIT License - Same as VoiceMode