/add-listen-hotkey

Install a global hotkey that triggers deus listen from anywhere on the OS. Also installs all required dependencies (sox, whisper-cli) and downloads the whisper model.

Step 1 — Install dependencies and whisper model

Run these checks and installs before asking the user about hotkey preferences.

Dependencies

macOS:

bash
1# Check sox
2command -v sox || brew install sox
3
4# Check whisper-cli (from whisper-cpp)
5command -v whisper-cli || brew install whisper-cpp

Linux:

bash
1# Check sox
2command -v sox || sudo apt install -y sox libsox-fmt-all
3
4# Check whisper-cli — not in apt, build from source if missing
5if ! command -v whisper-cli; then
6  echo "whisper-cli not found. Build from: https://github.com/ggerganov/whisper.cpp"
7  echo "After building, ensure 'whisper-cli' is on your PATH."
8  # Pause and ask user to confirm before continuing
9fi

Windows:

powershell
1# Check sox
2if (-not (Get-Command sox -ErrorAction SilentlyContinue)) {
3  winget install sharkdp.bat  # or: choco install sox.portable
4}
5
6# Check whisper-cli
7if (-not (Get-Command whisper-cli -ErrorAction SilentlyContinue)) {
8  Write-Host "Download whisper-cli from: https://github.com/ggerganov/whisper.cpp/releases"
9  Write-Host "Add it to your PATH, then re-run this skill."
10  # Stop and wait for user
11}

Whisper model

Resolve the model path from WHISPER_MODEL env var, or default to ~/deus/data/models/ggml-large-v3-turbo.bin (Liam's personal config) or ~/deus/data/models/ggml-base.bin (public default).

If the model file doesn't exist, download it:

bash
1MODEL_PATH="${WHISPER_MODEL:-$HOME/deus/data/models/ggml-base.bin}"
2MODEL_URL="https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-base.bin"
3
4if [ ! -f "$MODEL_PATH" ]; then
5  mkdir -p "$(dirname "$MODEL_PATH")"
6  echo "Downloading whisper model (148 MB)..."
7  curl -L --progress-bar -o "$MODEL_PATH" "$MODEL_URL"
8  echo "Model saved to: $MODEL_PATH"
9fi

For ggml-large-v3-turbo.bin (higher accuracy, 1.5 GB):

https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v3-turbo.bin

Ask the user which model they want if WHISPER_MODEL is not already set:

• base (148 MB, fast, good for English) — default
• large-v3-turbo (1.5 GB, best accuracy, recommended for Hebrew)

Set WHISPER_MODEL in ~/.zshrc / ~/.bashrc / Windows user environment variables so deus listen always finds the model without specifying it each time.

Verify end-to-end

Run a quick smoke test before installing the hotkey:

bash
1DEUS_LISTEN_NO_CLIPBOARD=1 node ~/deus/dist/deus-listen.js --help 2>/dev/null || \
2  echo "Build needed — run: cd ~/deus && npm run build"

If the build is missing, run npm run build in ~/deus before proceeding.

Step 2 — Detect OS and ask for hotkey preferences

Detect the OS (IS_MACOS / IS_LINUX / IS_WINDOWS from platform.ts context, or run uname -s).

Ask the user:

1. Hotkey — default Cmd+Option+V (macOS) / Super+Alt+V (Linux) / Ctrl+Alt+V (Windows)
2. Mode:
   • silent (default) — runs deus listen in background, notification on completion
   • terminal — opens a new terminal window with the VU meter visible
3. Stream mode? — if yes, uses deus listen --stream instead of single-shot

Step 3 — Install per OS

macOS — Hammerspoon

Check if Hammerspoon is installed: ls /Applications/Hammerspoon.app 2>/dev/null If missing: brew install --cask hammerspoon (ask user to approve).

Write ~/.hammerspoon/deus-listen.lua:

lua
1-- deus listen hotkey (managed by Deus /add-listen-hotkey)
2local mods = {"cmd", "alt"}
3local key  = "v"
4
5hs.hotkey.bind(mods, key, function()
6  -- SILENT MODE: run headless, notify on completion
7  local task = hs.task.new("/bin/zsh", function(code, stdout, stderr)
8    local msg = code == 0 and "Copied to clipboard" or "Transcription failed"
9    hs.notify.new({title = "Deus", informativeText = msg}):send()
10  end, {"-lc", "deus listen --no-clipboard=false"})
11  task:start()
12  hs.notify.new({title = "Deus", informativeText = "Listening…"}):send()
13end)

For terminal mode replace the task body with:

lua
1  hs.execute("open -a Ghostty --args -e 'deus listen'")

(or iTerm2 / Terminal.app if Ghostty is absent — detect with ls /Applications/Ghostty.app).

Source the file from ~/.hammerspoon/init.lua:

lua
1-- Auto-appended by Deus /add-listen-hotkey
2require("deus-listen")

Reload Hammerspoon: open -g hammerspoon://reloadConfig

Linux — sxhkd

Check if sxhkd is running: pgrep sxhkd If missing: sudo apt install sxhkd (or pacman/dnf equivalent).

Append to ~/.config/sxhkd/sxhkdrc (create if missing):

# deus listen (managed by Deus /add-listen-hotkey)
super + alt + v
    deus listen

For stream mode: replace deus listen with deus listen --stream.

Reload: pkill -USR1 sxhkd

For terminal mode (VU meter visible):

super + alt + v
    ghostty -e deus listen

Windows — AutoHotkey v2

Check if AHK is installed: Get-Command autohotkey.exe -ErrorAction SilentlyContinue If missing: winget install AutoHotkey.AutoHotkey

Write %APPDATA%\deus\deus-listen.ahk:

ahk
1; deus listen hotkey (managed by Deus /add-listen-hotkey)
2^!v:: {  ; Ctrl+Alt+V
3    Run "deus listen", , "Hide"
4}

For terminal mode: Run "wt.exe deus listen" (Windows Terminal).

Add to startup: create a shortcut in %APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup\.

Run immediately: Start-Process autohotkey.exe "$env:APPDATA\deus\deus-listen.ahk"

Step 4 — Verify

Test the hotkey:

• macOS: trigger it, wait for "Listening…" notification, speak, check clipboard.
• Linux: trigger, speak, check xclip -o -selection clipboard.
• Windows: trigger, speak, check Get-Clipboard.

Step 5 — Uninstall instructions (show to user)

• macOS: delete ~/.hammerspoon/deus-listen.lua, remove the require line from init.lua, reload Hammerspoon.
• Linux: remove the appended block from ~/.config/sxhkd/sxhkdrc, pkill -USR1 sxhkd.
• Windows: delete %APPDATA%\deus\deus-listen.ahk and the startup shortcut.