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/AutomateScale/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.

Is Vox on? Turning it on and off

Vox is on when the alien icon sits in your menubar (and the tiny alien idles at the bottom of the screen). It launches at login automatically — you normally never think about it. If it’s off: ⌘-Space → type “Hammerspoon” → return (Hammerspoon is Vox’s engine; Vox loads with it in seconds). If the icon is there but Vox feels dead: click the Hammerspoon menubar icon → Reload Config. Still weird? bash ~/vox/doctor.sh tells you exactly what’s wrong. To turn Vox fully off: quit Hammerspoon from its menubar icon.

open -a Hammerspoon     # turn Vox on from Terminal

Dictating while music or a podcast plays

Menubar alien → While recording: pick Duck audio (drops your Mac’s volume to 15%), Mute audio (total silence, zero mic bleed), or Pause media (your podcast/music pauses when you start talking and resumes when you release — you miss nothing). Using an external mixer or audio interface (Rodecaster, Focusrite, etc.)? Those play audio outside the Mac, so make sure the channel feeding your Mac carries only your mic — if the mixer folds your music/podcast channel into that feed, it gets transcribed along with your voice and no software ducking can help.

Backups, history & the graph

The brain snapshots itself to iCloud Drive → VoxBackups every day (newest seven kept; zero-outbound mode keeps them local instead). Restore any snapshot with python3 ~/vox/mem.py import <file>. Your last ten dictations live under the menubar alien → Recent dictations — click one to paste it again if an app ate it. And Open knowledge graph draws everything the brain knows as an interactive map.

python3 ~/vox/mem.py backup     # snapshot now
python3 ~/vox/mem.py export     # portable brain file to Desktop
python3 ~/vox/mem.py graph      # rebuild the interactive graph

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/AutomateScale/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/AutomateScale/vox/main/uninstall.sh | bash -s -- --yes
git clone https://github.com/AutomateScale/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.