Hotkey reference¶

A quick-glance card for the keys Quill listens to, the modifier symbols each operating system uses, and the combos you should not bind because the OS already owns them. Bookmark it. Print it. Tape it to your monitor.

For setting + changing the binding from inside the app, see First dictation → Pick your hotkey. For diagnosing a hotkey that refuses to fire, see Troubleshooting → Hotkey doesn't trigger.

What you can bind today¶

Quill alpha ships two independent hotkeys:

Setting	Default	What it does
Quick capture	`F8`	Hold to dictate. Raw Whisper text is injected when you release.
Enhanced capture	`F9` (or off)	Same hold-to-dictate loop, but runs the polish pass over the transcript before it lands.

Both bindings live in Settings → Capture and the picker is click-to-capture — open Settings, click Set hotkey, press the combo you want, and Quill commits it. The change takes effect immediately; no restart.

alpha.7 constraint — single key or bare modifier only

The daemon's listener (rdev) currently binds one key with no modifier state. That means the picker accepts these shapes today:

Function keys — F1–F12.
Bare modifiers — Right Shift, Right Control, Right Option, Right Command. (The picker always uses the right-hand modifier so the left-hand one stays free for normal text input.)
Lock keys — Caps Lock, Scroll Lock. (Reachable by hand-editing settings.toml; the picker doesn't surface them because they're easy to bind by accident.)

If you press something like Cmd+Shift+Space, the picker echoes the chord back and tells you it isn't bindable yet — your existing binding stays put. Modifier-aware chord support is tracked under issue #194.

Modifier symbols by OS¶

The same physical key prints differently across operating systems. Quill's picker shows the OS-native symbol; this table is the Rosetta Stone:

Concept	macOS	Linux	Windows
Command / Meta / Super	`⌘ Cmd`	`Super` (also called `Meta` / `Win`)	`Win`
Control	`⌃ Ctrl`	`Ctrl`	`Ctrl`
Option / Alt	`⌥ Opt`	`Alt`	`Alt`
Shift	`⇧ Shift`	`Shift`	`Shift`
Return / Enter	`↩ Return`	`Enter`	`Enter`
Escape	`⎋ Esc`	`Esc`	`Esc`
Backspace / Delete	`⌫ Delete`	`Backspace`	`Backspace`

In Quill's settings file, modifiers always serialise as Cmd, Ctrl, Alt, Shift regardless of OS — a Linux TOML and a macOS TOML are interchangeable. Aliases are accepted on input (Command, Option, Win, Super, Meta), but the canonical form on disk is always one of the four short names.

macOS reference card¶

  ┌────────────────────────────────────────────────────────────┐
  │  Default bindings on macOS                                 │
  │                                                            │
  │    Quick capture     [ F8 ]                                │
  │    Enhanced capture  [ F9 ]                                │
  │                                                            │
  │  Recommended alternatives                                  │
  │                                                            │
  │    [ Right ⇧ Shift ]   — works in every text field         │
  │    [ Right ⌃ Control ] — never shadows ⌘C / ⌃Tab           │
  │    [ Right ⌥ Option ]  — free on stock macOS               │
  │    [ Right ⌘ Command ] — only conflicts on weird IMEs      │
  └────────────────────────────────────────────────────────────┘

Why right-hand modifiers? Pressing the left ⌘ still triggers macOS app shortcuts (⌘C, ⌘V, ⌘Q) — Quill watches for the right-hand key only, so your normal shortcuts keep working untouched.

macOS — combos to avoid¶

These combos are owned by macOS or by common apps. Quill's picker shows an inline "may conflict with X" chip when you try to bind one — it doesn't block the save (you might genuinely want to override), but you'll want to know what you're stealing:

Combo	Owned by
`⌘ Space`	Spotlight
`⌘ ⌥ Space`	Spotlight (alternate)
`⌘ Tab`	App switcher
`⌘ ⇧ Tab`	Reverse app switcher
`⌘ Q`	Quit (current app)
`⌘ W`	Close window
`⌘ H`	Hide app
`⌘ M`	Minimise
`⌘ ⇧ 3`	Screenshot (whole screen)
`⌘ ⇧ 4`	Screenshot (region)
`⌘ ⇧ 5`	Screenshot tool
`⌃ ↑`	Mission Control
`⌃ ↓`	App Exposé
`⌃ ←` / `⌃ →`	Space switch (between desktops)

macOS — permissions checklist¶

Two permission gates have to flip before a hotkey fires:

Permission	Where	Why
Input Monitoring	System Settings → Privacy & Security → Input Monitoring	Lets Quill watch for the global hotkey press across apps.
Accessibility	System Settings → Privacy & Security → Accessibility	Lets Quill inject the polished text into the focused field. Without this, Quill falls back to clipboard paste.

The first time you hold your hotkey, macOS prompts for Input Monitoring. If you accidentally deny it, see Troubleshooting → Accessibility permission denied.

Linux reference card¶

  ┌────────────────────────────────────────────────────────────┐
  │  Default bindings on Linux                                 │
  │                                                            │
  │    Quick capture     [ F8 ]                                │
  │    Enhanced capture  [ F9 ]                                │
  │                                                            │
  │  Recommended alternatives                                  │
  │                                                            │
  │    [ Right Shift ]   — works on X11 and most Wayland       │
  │    [ Right Ctrl ]    — same                                │
  │    [ Right Alt ]     — conflicts with AltGr on some        │
  │                        layouts                             │
  └────────────────────────────────────────────────────────────┘

Linux — Wayland vs X11¶

Session type	What works	What doesn't
X11	Function keys, bare right-hand modifiers, all combinations supported by `rdev`. The daemon hooks the X server's global key grab.	Nothing Quill-specific.
Wayland (GNOME, KDE, sway, …)	Function keys + bare modifiers via `rdev`'s evdev backend, only if your user is in the `input` group (`sudo gpasswd -a $USER input` then log out + back in).	Compositor-level global hotkeys (`Super+Space`, `Super+L`, etc.) are owned by the compositor and never reach Quill. Some compositors don't deliver any global key events to non-portal apps — see the Wayland troubleshooting section for the per-compositor workaround.

Linux — combos to avoid¶

Combo	Owned by
`Alt+Tab`	App switcher (window cycle)
`Alt+F4`	Close window
`Ctrl+Alt+Del`	Secure attention sequence (GNOME logout / KDE shutdown menu)
`Super` / `Win` alone	GNOME Activities / KDE menu (compositor-level)

Compositor reservations (Super+Space, Super+L, Ctrl+Alt+T, …) vary by desktop environment. The general rule: if it works as a shortcut without Quill running, don't try to bind it.

Windows reference card¶

Windows packaging is on the roadmap

Quill doesn't ship a Windows binary in the alpha. When the Windows port lands, this card will document the Win-key conventions (Win+L, Win+R, Win+Tab, Ctrl+Alt+Del) and the modifier-symbol mapping.

Track the Windows port under issue #93.

The hold-talk-release loop¶

Whatever combo you bind, the loop is the same:

  Press and hold <your hotkey>   ┐
                                 │  ← Quill is recording.
  Speak naturally.               │     Menu-bar icon turns red.
                                 │
  Release <your hotkey>          ┘

         ↓ (~200ms — Whisper transcription)

  raw transcript                 ← in the Activity log

         ↓ (~300–800ms — local LLM polish)

  polished transcript            ← replaces the raw line

         ↓ (instant)

  text appears in your           ← focused field gets the text
  focused window

For the full walkthrough — first launch, model picker, permission grants — read First dictation.

Picking a hotkey that won't fight you¶

A short opinionated guide, in priority order:

Prefer a function key (F1–F12). They're free on every OS, they don't interfere with text entry, and the picker can capture them in one click. F8 is the default for a reason.
If you're a Vim / Emacs user, function keys are still your friend — F8 is unbound in most distributions of both. Avoid F1 (Vim opens help) and F11 (full-screen on most OSes).
A bare right-hand modifier is the next best. Right Shift is the safest because the right Shift key is almost never used in text shortcuts. Right Control and Right Option are fine too.
Avoid Caps Lock unless you've already remapped it to something else at the OS level — most users hit it by accident and would rather not start recording every time.
Don't bind Right Command on macOS if you use a Magic Keyboard with Touch ID — fingerprint reads route through that key on some models.

If your chosen hotkey conflicts with an app you care about, change it in Settings → Capture. The change is live.

Recovering from a stuck hotkey¶

If your hotkey suddenly stops responding mid-session, the most common cause is that another app has grabbed the key for itself (macOS Stage Manager, Linux compositor shortcut, …). See Troubleshooting → Hotkey doesn't trigger.

The fast recovery path: open Quill → Settings → Capture, click Set hotkey, press a different key. The daemon re-registers immediately.