Local NSEvent Monitors on macOS: Interception and Safe Teardown

An AppKit local event monitor observes copies of selected events that the application receives before dispatch. Its handler can return the event unchanged, return a replacement event, or return nil to stop the event from reaching normal dispatch. That makes it a powerful interception point, but also a sharp tool: an overly broad monitor can make ordinary controls, shortcuts, or accessibility interactions stop working.

Use the responder chain, a control action, or a gesture recognizer when the interaction belongs to a particular view or control. A local monitor is appropriate when a feature must observe or transform a class of app events across multiple windows before the responder chain handles them, such as a temporary key sequence for a modal tool. It is not a substitute for app-wide command architecture.

Install only for the active interaction

Store the opaque monitor token and remove it when the interaction ends. The monitor should have a clear owner such as a window controller or transient tool session. Avoid installing permanent monitors from every view controller; multiple monitors can transform or swallow the same event in an order that is difficult to diagnose.

import AppKit

final class TemporaryKeySequenceMonitor {
    private var token: Any?

    func begin() {
        guard token == nil else { return }
        token = NSEvent.addLocalMonitorForEvents(matching: .keyDown) { [weak self] event in
            guard let self else { return event }
            return self.shouldConsume(event) ? nil : event
        }
    }

    func end() {
        guard let token else { return }
        NSEvent.removeMonitor(token)
        self.token = nil
    }

    private func shouldConsume(_ event: NSEvent) -> Bool {
        // Match only the active tool's explicit key sequence.
        _ = event
        return false
    }

    deinit {
        end()
    }
}

The sample returns the original event for everything it does not explicitly handle. That pass-through rule should be the default. Consume an event only when the feature has a specific, documented reason and the user has entered the corresponding interaction mode. If the monitor is installed for a temporary mode, display that mode visibly and provide an obvious Escape or cancel path.

An NSEvent monitor token is not a general observer object. Keep it private to its owner, remove it exactly once, and clear the token. If a callback has already begun when the monitor is removed, it may finish; ensure its owner can tolerate a late call and does not mutate a closed document.

Understand the dispatch boundary

The handler receives the event before AppKit sends it through the application’s normal sendEvent path. A local monitor can change what the responder chain receives, but it does not take ownership of every possible input pathway. Apple documents that events consumed by nested tracking loops such as menu tracking, control tracking, or window dragging do not reach the local monitor.

That means a local monitor is not an exhaustive audit mechanism and cannot guarantee that every key or click is observed. A menu may handle its own tracking; a control may own a drag loop; a gesture recognizer may interpret a sequence. Use the abstraction that owns the interaction instead of trying to reconstruct all input from a global hook.

Global event monitors have different semantics: they receive copies of events sent to other applications and cannot modify or suppress those events. This article focuses on local monitors. Do not broaden a local input feature into systemwide observation without a separate product, consent, and privacy review.

Keep the event handler bounded

Monitor callbacks run on the event-delivery path. Keep them quick and deterministic: inspect a few fields, update a small mode state, and return the correct event. Do not synchronously fetch data, block on a lock held by the UI, write files, or perform network work. An event handler that pauses can make the entire app feel unresponsive.

If expensive work is needed, capture only the minimal immutable values and hand it to a separately owned task. Do not pass the NSEvent itself into unrelated background work and assume it remains a safe representation of the user’s input. If the task might complete after the interaction ends, attach a generation identifier and discard stale results.

Avoid re-posting a replacement event from inside the monitor unless the design explicitly prevents recursion. The replacement event can re-enter the same monitor and be transformed repeatedly. Returning an event from the callback is normally the simpler contract. Test any intentional event synthesis separately and guard it with a narrowly scoped state flag.

Keyboard interpretation and pass-through

Keyboard events contain characters, modifier flags, key codes, repeat state, and input-method context. Do not treat characters as a universal physical key identifier. Keyboard layouts and input methods affect characters; hardware key codes represent another layer. For text input, use AppKit’s text-input system rather than intercepting and reimplementing composition.

Restrict the event mask to the smallest set needed. A key-sequence monitor should generally not intercept all mouse and scroll events. Even with a narrow mask, preserve commands the user expects, allow Escape to cancel where appropriate, and ensure the same operation remains accessible via menus or other supported controls.

Be careful around repeat events. A held key can produce repeated key-down events, and a monitor that handles only the first event can leave an internal state stuck if it relies on receiving all repeats. Track begin/end semantics where needed and reset transient state on window deactivation or session cancellation.

Avoid fighting the responder chain

The monitor runs before normal application dispatch, so it should not duplicate command logic already implemented by menu validation, performKeyEquivalent, or the first responder. If a shortcut is a persistent app command, expose it through the normal menu and key-equivalent system so the user can discover it, so enabled state follows current model state, and so accessibility technologies can invoke it. Reserve local monitoring for a temporary interaction that genuinely needs a pre-dispatch decision.

When deciding whether to consume a key, check modifiers and the active mode as well as the character. A character string can be localized by the keyboard layout, while a physical key code has different semantics. The correct representation depends on whether the product means “the character typed” or “this physical key.” Use text-input APIs for text composition and avoid consuming events while an input method is composing marked text.

If a temporary mode starts in one window and another window becomes key, choose whether the mode follows the app or remains attached to its origin window. Cancel or rebind it explicitly on a key-window transition. This prevents a shortcut intended for a canvas from unexpectedly consuming keys in a Preferences window or a different document.

Multiple monitors and diagnostic isolation

Monitors can be composed, but each extra layer adds another pass-through decision and teardown obligation. Prefer one coordinator that routes to the active feature over a chain of independent monitors. If independent features need monitors, make installation order and ownership explicit and test that removing one handler does not disable another feature.

When debugging, temporarily log event type, key code, modifier flags, window number, responder class, and monitor generation in a local development build. Do not leave detailed key logging enabled for production. Use a short captured test with synthetic or non-sensitive input, then remove the diagnostic hook. Persistent keystroke logs create a privacy risk and rarely improve a durable fix.

Window and document ownership

If the monitor applies to one document window, verify the event’s window and responder context before consuming it. A monitor registered at app level can receive events for more than one window owned by the app. Checking only the key code may swallow a shortcut in an unrelated document.

Tie monitor start and stop to an explicit tool state. When the user changes documents, closes a window, cancels a panel, or the feature is disabled, remove the monitor. Do not rely only on deinit, especially when a controller is retained by other app state. If multiple windows can enter the same mode, use a shared coordinator or separate mode tokens so one window cannot remove another’s monitor.

Record only the operation and outcome needed for diagnostics. Avoid logging typed characters, full key sequences, or sensitive document context. If the feature needs input capture, explain the behavior and limit it to the active user-facing interaction.

Validation matrix

Test a matching key, a nonmatching key, a key repeat, Escape cancellation, an unrelated window, a menu tracking loop, a control drag, a window drag, an input method composition, monitor installation twice, end twice, and owner teardown during a callback. Confirm that unrelated commands and text entry still work and that the monitor does not remain installed after the feature ends.

Instrument monitor start/stop, event type, selected mode, and whether the event was passed through or consumed. Avoid capturing event contents in production logs. A focused diagnostic should answer whether the monitor was active and which policy branch ran without reproducing private input.

Local event monitors provide a pre-dispatch hook for narrow application-level interactions. Keep them temporary, preserve events by default, account for nested tracking loops, and remove the token when ownership ends. Use ordinary controls and responder routing for everything they can express more clearly.

Related:

Sources: