Configurable hotkey, paste-based injection, overlay above full-screen

[Entrepenulian]

Three things the docs promise that the code never implemented. Each one makes parrot unusable on some setup.

--hotkey

HotkeyMonitor hardcoded .maskSecondaryFn, so the README's parrot --hotkey right-option did nothing.

This matters more than a missing flag: non-Apple keyboards handle Fn in firmware. It reshapes the F-row locally and never sends anything to the host, so no application can bind to it. On a Mac mini with a third-party keyboard there is no working key at all — parrot waits forever for an event the hardware cannot produce.

Adds a Hotkey enum for fn plus the left/right variants of option, command, control and shift. Left and right share one event flag, so each case carries a keycode and the monitor filters on it before reading the flag.

--inject-mode

CGEventKeyboardSetUnicodeString is discarded by terminals and WebKit/Electron-hosted UIs, which read key events directly. Dictation worked in Safari and silently produced nothing in a terminal.

Adds the inject_mode from docs/architecture.md, defaulting to paste: stage the text, send ⌘V, restore the pasteboard. Two details worth reviewing:

• the snapshot preserves every representation of every item, so dictating while an image or file is copied doesn't destroy it
• a pending restore suppresses re-snapshotting, so two transcripts inside the settle window can't leave the first one on the pasteboard permanently

Verified in a terminal. type-unicode remains available for anyone who wants the pasteboard untouched.

Overlay

The pill sat at .statusBar, below full-screen windows, so it was invisible whenever the frontmost app was full-screen — measured as layer=25 onscreen=false during an active recording. Now .screenSaver.

Also repositions on every show, since the active screen and Space change between recordings; picks the screen under the pointer rather than NSScreen.main, which follows keyboard focus and is nil for a background agent; and generation-guards the dismiss timer so a recording started inside the 0.18s animation isn't ordered back out by the previous hide.

Install

The LaunchAgent hardcoded its arguments, so launch-at-login silently reverted both new settings. Easy to miss — it only bites after a reboot.

---

Default choice worth a second opinion: paste briefly touches the clipboard. It's the mode that works everywhere, which is why it's the default, but type-unicode as default is a one-line change if you'd rather not touch the pasteboard by default.

Tested on macOS 26.5 / M4 with a Logitech keyboard, on left-option + paste. The other seven modifiers share one code path and a keycode table, but only left-option was exercised on hardware.

🤖 Generated with Claude Code

[justintime]

I would love to see this get merged. The README.md on main already reports it as an available option:

parrot --hotkey right-option           # change the push-to-talk key

But it's not there because this PR is still open :) My use case is a Mac Mini with a mechanical keyboard that has no Fn key.

[rretsiem]

Implemented in the current Parrot working tree:\n\n- Added configurable hotkey support with side-specific modifier matching.\n- Added paste and type-unicode injection modes. Paste preserves all clipboard items and representations, protects against overlapping restores, user clipboard changes, focus drift, secure fields, and unknown focus.\n- Raised the recording overlay above full-screen apps and repositioned it using the screen under the pointer.\n- Added --inject-mode and updated the docs. Login startup uses the saved hotkey and safe paste mode through SMAppService; CLI overrides remain per launch.\n\nVerification: swift build passed. swift test passed with 347 tests and 0 failures. Focused injection and overlay tests also passed.