All pages
Docs · AI features
Agent Lock
Availability: macOS only. Built on CGEventTap and a full-screen overlay; there is no non-macOS equivalent planned.
Agent Lock blocks every physical input and overlays your screens for the duration of an agent run. Use it when the agent is doing something you want to leave alone — overnight migrations, long browser automations, anything where an accidental keystroke would corrupt the work.
When armed:
- A fullscreen overlay covers every connected display at the shielding level macOS uses for its own lock screen — above fullscreen apps
- Keyboard, mouse, trackpad, and macOS hotkeys (Cmd-Tab, Cmd-Q, Mission Control, brightness keys, function keys) are dropped at the HID level before WindowServer sees them
- A power assertion keeps the Mac from idle-sleeping for the duration of the run
- Closing the lid / sleeping the Mac still works as an intentional escape hatch — on wake, the macOS login screen provides equivalent auth before you can resume. Locking the session (Ctrl-Cmd-Q, the Touch ID button) disarms the same way for the same reason.
Arming
Click the lock button in the sidebar rail ("Lock Desktop") to arm. If VoiceOver or Switch Control is enabled, arming is refused — those assistive paths can route around the input tap, so the lock won't pretend to hold. If the input tap can't be installed (Accessibility / Input Monitoring permission missing), an alert explains and deep-links to System Settings.
The overlay shows:
- A status line ("TRMNLY agent is running — input is blocked")
- The elapsed time since arming
- An Unlock button, plus an Esc fallback to type your password directly into the overlay if the system prompt fails to appear
If VoiceOver or Switch Control gets switched on mid-run (the controller polls every 2 seconds), the Agent Lock status card in the right sidebar raises a visible alarm. It deliberately does not auto-disarm — auto-disarming would itself be the bypass.
Unlocking
Click the overlay's unlock button (or press any physical key — the first event is consumed to trigger the auth prompt). The macOS LocalAuthentication framework prompts for your account password or Touch ID. On success, the controller disarms immediately and your input flows again.
The HID event tap is briefly disabled while auth is on screen so SecurityAgent can draw above the overlay.
Synthetic events
Agent tools that need to send real keystrokes or mouse events (the
OS automation surface) route through
AgentLockController.shared.syntheticEventSource while the lock is
armed. That event source is allow-listed at the tap, so the agent's
own clicks pass through but yours don't.
Fail-safe watchdog
Arming also spawns a second process that watches the app itself. If
TRMNLY crashes, is force-quit, or is kill -9'd while the lock is
armed, the watchdog locks the real macOS screen — so an abnormal exit
can never leave the Mac unlocked and unattended. A clean disarm
dismisses the watchdog silently.
While armed, ordinary termination signals (kill <pid> from an SSH
session, for example) are ignored so they can't drop the lock. sudo kill -9 and a hard power-off still win — and then the watchdog covers
the gap.
Failure modes
If the HID tap fails to install or dies mid-run — Accessibility or Input Monitoring permission revoked — the controller self-disarms and the overlay drops, with the reason surfaced in the status card. Better an unlocked agent than a screen you can't get out of.
The controller also self-disarms on system sleep and on session lock; re-arm from the sidebar button after wake. As a last resort, unlocking the macOS session itself always sweeps away any leftover lock state.