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:

Detecting your platform - Identifies your OS, distribution, and architecture
Checking dependencies - Scans for required system packages
Installing packages - Uses your system's package manager (apt, dnf, brew)
Installing VoiceMode - Runs uv tool install voice-mode
Hardware recommendations - Suggests optimal configuration for your system
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

Platform Detection - Identifies OS, distribution, and architecture
Dependency Checking - Compares installed packages against dependencies.yaml
Package Manager Setup (macOS only) - Checks for Homebrew and offers to install if missing
Package Installation - Uses platform-specific package managers:
- macOS: brew install (installs Homebrew first if needed)
- Ubuntu/Debian: sudo apt install
- Fedora: sudo dnf install
VoiceMode Installation - Runs uv tool install voice-mode[==version]
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

Check the log file: ~/.voicemode/install.log
Try a dry run: uvx voice-mode-install --dry-run
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

Release files for voice-mode-install 8.12.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for voice-mode-install 8.12.0
File	Size	Uploaded
voice_mode_install-8.12.0.tar.gz	16.4 kB	Jul 21, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for voice-mode-install 8.12.0
File	Interpreter	ABI	Platform	Reset
voice_mode_install-8.12.0-py3-none-any.whl 19.1 kB Jul 21, 2026	Python 3	none	any	Details

Total release size: 35.5 kB

Release files / voice_mode_install-8.12.0.tar.gz

Download URL	voice_mode_install-8.12.0.tar.gz
Size	16.4 kB
Tags	Source
SHA-256 checksum How to use checksums	`b477b6f31daaf4058e81e1ec71eb3d6f76ece86e6c6997585bc089d0d3925d6f`
BLAKE2b-256 checksum How to use checksums	`8a12da574622748968ff3aa6f0e1a65c54daebee22e3d4989f48d42c2a2aa17d`
Upload date	Jul 21, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/mbailey/voicemode
Publishing commit: github.com/mbailey/voicemode/tree/5c1b3e4d9421cd365d039da1d29827a0a83a18c7

Workflow

Publishing configuration: github.com/mbailey/voicemode/blob/5c1b3e4d9421cd365d039da1d29827a0a83a18c7/.github/workflows/publish-pypi-and-mcp.yml
Publishing logs: github.com/mbailey/voicemode/actions/runs/29830975228/attempts/1

Artifact

Subject: voice_mode_install-8.12.0.tar.gz
SHA-256 checksum: b477b6f31daaf4058e81e1ec71eb3d6f76ece86e6c6997585bc089d0d3925d6f Verifying attestations

Release files / voice_mode_install-8.12.0-py3-none-any.whl

Download URL	voice_mode_install-8.12.0-py3-none-any.whl
Size	19.1 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`e4d574698b99eea2c9e44a286ead923ea4ff838224236b701d602e023ddce1d7`
BLAKE2b-256 checksum How to use checksums	`0dd2faff4df5ebfc35f7f9b969a68bb3ec0e538e6c24acf04414c3f0e32bd979`
Upload date	Jul 21, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/mbailey/voicemode
Publishing commit: github.com/mbailey/voicemode/tree/5c1b3e4d9421cd365d039da1d29827a0a83a18c7

Workflow

Publishing configuration: github.com/mbailey/voicemode/blob/5c1b3e4d9421cd365d039da1d29827a0a83a18c7/.github/workflows/publish-pypi-and-mcp.yml
Publishing logs: github.com/mbailey/voicemode/actions/runs/29830975228/attempts/1

Artifact

Subject: voice_mode_install-8.12.0-py3-none-any.whl
SHA-256 checksum: e4d574698b99eea2c9e44a286ead923ea4ff838224236b701d602e023ddce1d7 Verifying attestations