Vox Docs - Install, Troubleshoot, Uninstall

Install (new Mac) — one line

curl -fsSL https://automatescale.com/vox/install | bash

Bootstraps everything (even Homebrew and git if missing), then walks you through the two permission grants — including auto-detecting the Accessibility grant and popping the Microphone prompt. Safe to re-run anytime. Prefer manual? Same thing:

Install (manual)

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 ~1.5s. Double-tap for hands-free lock (tap again to stop). Triple-tap = smart reply: Vox reads the window on screen and drafts the best response. Shift + hold = expand mode: speak a rough idea, get polished content back.

Start a dictation with “Hey Vox, …” and instead of pasting, the alien answers your question from its own memory — on screen and in your clipboard.

Spoken commands: say “scratch that” to undo the last dictation; say “new paragraph.” or “new line.” for breaks. Say “uh” all you want — fillers are filtered out.

When idle, a tiny alien rests at the bottom of the screen: click him for hands-free dictation, C to speak-to-content, P to absorb whatever's on screen into your knowledge base.

The alien's brain

Every dictation is remembered locally in ~/vox/memory/ — a readable journal plus instant full-text recall. Names, brands, and recurring topics become entities that link to each other automatically; the menu's “Open memory wiki” shows the whole graph as a browsable site. The brain feeds Whisper's vocabulary (names you use spell correctly), powers smart replies and “Hey Vox” answers, and exports as one file to move or merge with another Vox: python3 ~/vox/mem.py export. Add a ~/vox/identity.md describing yourself and replies are written as you. Everything stays on your Mac.

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.