Vox Docs - Install, Troubleshoot, Uninstall

Install (new Mac)

git clone https://github.com/AutomateScaleInc/vox.git ~/vox
cd ~/vox && bash install.sh

Installs Hammerspoon, whisper.cpp, sox and Ollama via Homebrew, downloads the Whisper model (~575 MB), pulls the cleanup model, and wires everything up. Then grant two permissions when macOS asks: Accessibility and Microphone for Hammerspoon (System Settings → Privacy & Security).

Use it

Hold Right Option (⌥), speak, release — text pastes at your cursor in ~2s. Double-tap Right Option for hands-free lock, tap again to stop. The menu-bar alien has toggles: hotkey choice, language, translation, AI cleanup, music ducking, sound theme.

Update

cd ~/vox && git pull
killall Hammerspoon; open -a Hammerspoon

Broken after an update? Hard reset

cd ~/vox && git fetch origin && git reset --hard origin/main
killall Hammerspoon; open -a Hammerspoon

Your personal vocabulary (local.lua) and downloaded models are untracked — resets never touch them.

Diagnose anything

bash ~/vox/doctor.sh

Checks dependencies, the model, the full transcription pipeline, live mic level (speak during the 3-second test), and whether Hammerspoon actually holds the Microphone permission.

Personal vocabulary

cp ~/vox/local.example.lua ~/vox/local.lua
open -e ~/vox/local.lua

Add your brands, clients and jargon. local.lua is gitignored — it never leaves your machine. Copy it between your own Macs by hand.

Command-line access

hs -c 'print("accessibility: " .. tostring(hs.accessibilityState()))'

Vox self-installs the hs CLI so you (or an agent) can inspect and drive it from a terminal.

Uninstall / erase

bash ~/vox/uninstall.sh

Or from anywhere, even if ~/vox is broken or gone (no questions asked):

curl -fsSL https://raw.githubusercontent.com/AutomateScaleInc/vox/main/uninstall.sh | bash -s -- --yes

Backs up your local.lua to ~/vox-local.lua.bak, unwires Hammerspoon (preserving any non-Vox config), and removes ~/vox. Add --purge to also remove the Homebrew packages.

Nuke & reinstall (fixes almost everything)

cd ~
curl -fsSL https://raw.githubusercontent.com/AutomateScaleInc/vox/main/uninstall.sh | bash -s -- --yes
git clone https://github.com/AutomateScaleInc/vox.git ~/vox
cd ~/vox && bash install.sh
mv ~/vox-local.lua.bak ~/vox/local.lua 2>/dev/null; true

Every Vox command, copy-ready.