# Hotkeys

Example bindings that drive the assistant through `stt-ctl`. Pick your WM's tool:

- `sxhkdrc.example` — copy the lines into `~/.config/sxhkd/sxhkdrc`, reload sxhkd.
- `xbindkeysrc.example` — append to `~/.xbindkeysrc`, run `xbindkeys`.

Both need a running `stt-assistant` (and `stt-daemon` feeding it transcriptions).

## What the bindings do

| Binding intent | Command |
|---|---|
| Arm a command (next complete turn becomes an action) | `stt-ctl command-start` |
| Execute the armed command | `stt-ctl command-execute` |
| Cancel the armed command | `stt-ctl command-cancel` |
| Toggle chat mode | `stt-ctl chat-toggle` |
| Show the TUI | `stt-tui` |

Each `stt-ctl` call connects to the assistant's control socket, sends one message,
prints the reply, and exits — so it is safe to bind to a global hotkey.

## Why arm-then-execute

Arming is the strongest possible intent signal, and executing is a **second,
explicit press**. Nothing runs on a guess:

1. Press the arm hotkey — the TUI shows `command_armed`.
2. Speak. The transcript fills the command buffer live.
3. Optionally press `e` in the TUI to correct the text (fixes ASR mistakes before
   the model sees them).
4. Press execute — or cancel with `Esc`.

Command mode and chat mode are mutually exclusive, and `require_viewer = true`
means `command-execute` is refused unless a TUI is attached (so a stray hotkey
cannot fire an action with nobody watching).