Forem: QUICOPY

The macOS Global Shortcut That Won't Fire in Zed: When a 23-Year-Old Carbon API Meets a Self-Drawn Terminal

QUICOPY — Tue, 21 Apr 2026 03:38:43 +0000

TL;DR

A user reported that QUICOPY's global shortcut ⌘1 fires in iTerm2, Ghostty, Warp, and even in Zed's editor — but silently does nothing inside Zed's built-in terminal. Changing the key combo doesn't help. Restarting doesn't help.

The cause is not a key conflict. It's an event dispatch architecture mismatch: Carbon's RegisterEventHotKey (the API almost every indie macOS app uses for global hotkeys) only fires when the frontmost app doesn't consume the event. Zed's GPUI-based terminal consumes every keyDown: it sees. Carbon never gets a chance.

I originally planned a three-tier fallback (CGEventTap → NSEvent → Carbon) to cover every regime. What I actually shipped for the Mac App Store is two tiers (NSEvent + Carbon) plus a separate paste-strategy rewrite I didn't see coming. This post is the design log for both.

If you ship a macOS app with global shortcuts in 2026 and your users live in Zed, VS Code, or any Electron/Tauri/Flutter app that self-draws its text UI — you're going to hit this. Here's the full autopsy.

Correction from my last post

In my previous post I wrote that QUICOPY uses CGEvent.tapCreate to capture global shortcuts. That was a lie — or more precisely, what I had originally prototyped but never shipped. The released build uses Carbon RegisterEventHotKey, because CGEventTap requires an Accessibility permission prompt I wanted to avoid, and Carbon works out of the box in a sandboxed app with zero entitlements.

That decision is exactly what broke in Zed. This post is the correction.

The Bug Report

"I pressed ⌘1 in Zed's terminal. Nothing happens. Menu bar icon doesn't flash. No text inserted."

Compatibility matrix after reproducing:

Host app	`⌘1` fires?
iTerm2	✅
Ghostty	✅
Warp	✅
Zed — editor	✅
Zed — built-in terminal	❌
VS Code — editor	✅
VS Code — built-in terminal	❌
Chrome / Safari	✅

The failure is not about Zed the application. It's specifically about the terminal view inside Zed. That's a strange enough shape to rule out the usual suspects immediately.

Wrong Hypothesis #1: "Zed stole the key"

First instinct: Zed has its own ⌘1 binding (switch to tab 1, or switch pane), and it's grabbing the key before the OS routes it to anything else.

I unbound Zed's ⌘1 and tried again. Still broken.
I switched QUICOPY's shortcut to ⌘⌃F9 — a combination no sane app would ever claim. Still broken.

If you change the key and the bug stays, you're not looking at a key conflict. You're looking at something upstream of key identity.

Wrong Hypothesis #2: "My handler isn't registered"

Second instinct: maybe Carbon failed to install the hotkey when Zed became frontmost. Some shell-out race condition.

Logs from HotkeyManager:

[HotkeyManager] Started with 7 hot keys registered

All seven mappings register cleanly. But the Carbon callback — the function that Carbon is supposed to invoke when my hotkey matches — is never called when I press ⌘1 inside Zed's terminal.

Which means the problem isn't in my code. It's in the pipe before my code.

The Real Culprit: How Carbon Actually Dispatches

Carbon's event model is documented, but the documentation buries the critical detail. Here's the dispatch order for a keyDown event on modern macOS:

┌───────────────────────────────────────┐
│ Hardware → WindowServer → NSEvent     │
└──────────────────┬────────────────────┘
                   ▼
         ┌──────────────────┐
         │ Frontmost App    │  NSApplication.sendEvent:
         │ (AppKit)         │  → NSWindow.sendEvent:
         └────────┬─────────┘  → NSResponder chain
                  │
          ┌───────┴────────┐
          │                │
    event consumed   event not consumed
    (returns YES)    (returns NO / unhandled)
          │                │
          ▼                ▼
      STOP            ┌────────────────────┐
                      │ Carbon Event Mgr   │
                      │ RegisterEventHotKey│ ← your callback fires here
                      └────────────────────┘

Carbon's hotkey dispatch runs after the frontmost app has had a chance to handle the event, and only if the app reports "unhandled." This design comes from Carbon's original purpose: application-level shortcut registration for the frontmost app, extended over time to become a pseudo-global mechanism by registering at the process-group level.

For a traditional AppKit app, the responder chain dutifully returns "unhandled" for any key that doesn't match a menu item or an active text field. Carbon fires. All is well.

For an app whose text area is an NSTextView — iTerm2, Terminal.app, TextEdit — same story. NSTextView gracefully forwards keys it doesn't recognize.

But Zed's editor and terminal are not NSTextView.

Why Zed's Terminal Specifically: GPUI + Unconditional Consumption

Zed is built on GPUI, a Rust UI framework that renders its entire interface with Metal shaders. There are no NSTextView instances inside Zed's main content area — just a single NSView that captures raw input and dispatches it to GPUI's own keyboard handling.

Zed's terminal view uses a class called TerminalInputHandler (you can see traces of this in the open-source repo and in related bug reports: Zed #15517, Zed #16187). For every keyDown: event, TerminalInputHandler does one of two things:

If the key matches a registered Zed binding → run the Zed action, return handled
If nothing matches → forward the keystroke to the shell process (PTY write), return handled

Note the important word in both branches: handled. Zed's terminal never returns "unhandled" — because from its perspective, there's no such thing as an unhandled keystroke. Either it's a command or it goes to the shell.

This is perfectly correct behavior for a terminal. A terminal's whole job is to eat keystrokes. But it means Carbon upstream sees "app consumed the event" and refuses to fire any registered hotkey.

Changing the shortcut combo changes nothing. The event was consumed before Carbon was even consulted.

This is not a Zed bug. VS Code's integrated terminal, which uses xterm.js inside an Electron <canvas>, has the same behavior. Any modern self-drawn UI framework — Flutter macOS, Tauri with custom keyboard handling, JetBrains IDEs in certain modes — can reproduce this. Carbon's assumption that "the frontmost app will pass unknown keys through" has quietly rotted as native text views have been replaced by self-drawn ones.

What I Planned: A Three-Tier Auto Fallback

Three APIs can observe keyboard events system-wide. The tradeoffs are what make this interesting:

Mechanism	Intercept point	Fires even when app consumes	Sandbox-friendly	Permission	Can swallow event
`RegisterEventHotKey` (Carbon)	After frontmost app	❌	✅	None	✅
`CGEvent.tapCreate` (`.cgSessionEventTap`)	Before frontmost app	✅	❌ in MAS	Accessibility	✅
`NSEvent.addGlobalMonitorForEvents`	Outside frontmost app	✅	✅	Accessibility	❌

The two columns that matter: Fires even when app consumes and Can swallow event.

Carbon loses the first. That's our bug.
CGEventTap wins both — but Apple does not allow it in Mac App Store sandboxed apps. (Officially, com.apple.security.app-sandbox = true + event tap creation returns nil. Unofficially, confirmed across a half-decade of developer forum posts.)
NSEvent global monitor wins the first column and runs fine under sandbox, but cannot swallow events. So if you bind ⌘1 and the user is in Chrome, they'll both switch to the first tab and fire your shortcut. That's a bad experience for a text expansion tool.

No single backend wins. My original plan was to run all three behind a single protocol and pick at startup based on runtime conditions:

protocol HotkeyMonitoring: AnyObject {
    var isRunning: Bool { get }
    var isRecordingSuspended: Bool { get set }
    var onHotkeyTriggered: ((KeyMapping) -> Void)? { get set }
    func start(mappings: [KeyMapping]) -> Bool   // return false → caller falls through
    func stop()
    func updateMappings(_ mappings: [KeyMapping])
}

Three implementations:

HotkeyManager — the existing Carbon code, untouched
EventTapHotkeyManager — new, for non-sandbox + AX-authorized
NSEventHotkeyManager — new, for sandbox-safe fallback

Selection logic at launch and whenever Accessibility permission flips:

private func chooseBackend() -> any HotkeyMonitoring {
    let sandboxed = SandboxInfo.isSandboxed
    let axGranted = permissionManager.isAccessibilityGranted

    if !sandboxed && axGranted {
        return EventTapHotkeyManager()        // best: Zed-compatible + swallows
    }
    if axGranted {
        return NSEventHotkeyManager()          // sandbox fallback: Zed-compatible
    }
    return HotkeyManager()                     // zero-permission baseline
}

And subscribe to the permission flip so the user upgrades automatically once they grant Accessibility:

permissionManager.$isAccessibilityGranted
    .removeDuplicates()
    .dropFirst()
    .sink { [weak self] _ in self?.hotSwapBackend() }
    .store(in: &cancellables)

To detect the sandbox at runtime (rather than #if SANDBOXED), I planned to read the app's own entitlements via Security.framework:

enum SandboxInfo {
    static let isSandboxed: Bool = {
        guard let task = SecTaskCreateFromSelf(nil) else { return false }
        let value = SecTaskCopyValueForEntitlement(
            task,
            "com.apple.security.app-sandbox" as CFString,
            nil
        )
        return (value as? Bool) ?? false
    }()
}

I also sketched out the CGEventTap edge cases I'd have to handle:

.tapDisabledByTimeout / .tapDisabledByUserInput → re-enable, circuit-break after 3 consecutive failures, fall back to NSEvent
Fresh AX grant where tapCreate returns nil → treat as soft failure, fall back, show a one-time toast asking for restart
@MainActor isolation for the C callback — planned to be nasty
A generation token to reject stale callbacks after a backend swap

This was the plan. It's a satisfying bit of architecture on paper. It's not what I shipped.

What Actually Shipped: Two Tiers and a Paste Rewrite

QUICOPY ships only on the Mac App Store. The sandbox makes CGEventTap permanently unavailable for this target. Rather than maintain a tier of code that's statically unreachable in my only distribution channel, I collapsed the architecture to what actually runs:

protocol HotkeyMonitoring: AnyObject {
    var isRunning: Bool { get }
    var isRecordingSuspended: Bool { get set }
    var onHotkeyTriggered: ((KeyMapping) -> Void)? { get set }
    func start(mappings: [KeyMapping])
    func stop()
    func updateMappings(_ mappings: [KeyMapping])
}

Two implementations:

NSEventHotkeyManager — when Accessibility is granted
HotkeyManager — Carbon, when it isn't

Selection logic collapses to a single if:

private func chooseAndStartMonitor() {
    dispatchPrecondition(condition: .onQueue(.main))
    let suspended = activeMonitor?.isRecordingSuspended ?? false
    activeMonitor?.stop()

    let authed = permissionManager.isAccessibilityGranted
    let monitor: any HotkeyMonitoring = authed
        ? NSEventHotkeyManager()
        : HotkeyManager()
    installCallbacks(on: monitor)
    monitor.isRecordingSuspended = suspended
    monitor.start(mappings: mappingStore.mappings)
    activeMonitor = monitor
}

No start() -> Bool. No factory array. No assertionFailure hard-floor. No generation tokens. The code reads exactly as the design is: two states, one switch.

I still subscribe to the permission flip so the user upgrades automatically once they grant Accessibility:

permissionManager.$isAccessibilityGranted
    .removeDuplicates()
    .dropFirst()
    .receive(on: DispatchQueue.main)
    .sink { [weak self] _ in self?.chooseAndStartMonitor() }
    .store(in: &cancellables)

End state: grant AX → NSEventHotkeyManager starts → Zed's terminal receives ⌘1 events via the global monitor → QUICOPY fires its mapping. Revoke AX → chooseAndStartMonitor re-runs → Carbon comes back as the fallback → Zed's terminal stops responding (expected).

The trade-off you're making by shipping only NSEvent + Carbon on sandboxed macOS: when the user is in Chrome and hits ⌘1, Chrome still switches to its first tab and QUICOPY inserts its text. No backend can swallow the event in the sandbox. In practice users learn to avoid ⌘1..9 for bindings that collide with browser tab shortcuts, and the in-app permission screen suggests ⌘⌃1..9 or ⌘⌥1..9 combos instead.

The Surprise: Carbon Is Not the Only Thing That Broke in Zed

Getting the event to fire was half the fight. Getting text to actually appear in Zed's terminal was the other half — and this part isn't in any original design doc, because it only surfaced during the regression pass.

QUICOPY's text-output strategy on the MAS side has always been: write to the pasteboard → trigger Edit → Paste via AppleScript click menu item "Paste" of menu 1 of menu bar item "Edit". Menu click goes through AppKit's first-responder chain, doesn't depend on physical modifier keys, and is immune to IME state. It works beautifully in every NSTextView-based app.

In Zed's terminal, something very strange happens instead:

⌘1 fires (good — NSEvent monitor is working)
The onHotkeyTriggered callback runs (good)
TextOutputManager.output writes "hello world" to the pasteboard and runs the AppleScript
The AppleScript returns without error — my code logs paste path=menu_en, marks it as autoPasted, and celebrates
Nothing appears in the terminal

No error. No failure. The AppleScript says it clicked the Paste menu item, the menu item exists in Zed's Edit menu, and the click is reported as successful. But the paste doesn't actually happen.

The autoPasted Illusion

This is a deeply subtle bug. The old TextOutputManager judged "paste succeeded" purely by whether the AppleScript threw an exception:

script?.executeAndReturnError(&error)
if let error = error {
    return .clipboardOnly
}
return .autoPasted

But AppleScript's click menu item on a disabled-looking-but-technically-present menu item in a non-AppKit host returns no error and performs no visible action. Zed's Edit → Paste menu item is routed to whichever buffer GPUI considers focused — and when that focused buffer is the built-in terminal, the menu-click route apparently doesn't reach the terminal's input handler.

So the fix: stop trusting "AppleScript didn't throw" as a proxy for "paste happened." Ask AppleScript to check the menu item's enabled state explicitly, and fall back to synthesizing the keystroke directly when the menu route looks unreliable:

tell process frontProcess
    try
        set editMenu to menu 1 of menu bar item "Edit" of menu bar 1
        if exists menu item "Paste" of editMenu then
            if enabled of menu item "Paste" of editMenu then
                click menu item "Paste" of editMenu
                return "menu_en"
            end if
        end if
    end try
    try
        set editMenuZh to menu 1 of menu bar item "编辑" of menu bar 1
        if exists menu item "粘贴" of editMenuZh then
            if enabled of menu item "粘贴" of editMenuZh then
                click menu item "粘贴" of editMenuZh
                return "menu_zh"
            end if
        end if
    end try
    keystroke "v" using command down   -- fallback
    return "keystroke"
end tell

Two useful wins from this structure:

The three-way return value is a live diagnostic signal. In production logs I now see paste path=menu_en for iTerm2, paste path=menu_zh for localized apps, and paste path=keystroke for Zed, VS Code, and anything else self-drawn. When users report "paste doesn't work," the first question I ask is what path they're on.
keystroke is a real fallback, not a silent substitute. Menu click still wins by default for every normal AppKit app (IME-safe, modifier-key-safe), and keystroke kicks in only when the menu route is genuinely missing or disabled.

The Self-Paste Trap (a.k.a. error 1002)

While I was testing the paste rewrite, I hit another class of bug: what happens when the user presses a bound shortcut while QUICOPY's own popover is in the foreground?

Old behavior (Carbon): Carbon fires the callback, the callback writes to the pasteboard, AppleScript tries to keystroke ⌘V into the frontmost process — which is QUICOPY itself. macOS Accessibility policy then says:

"QUICOPY" is not allowed to send keystrokes. (Error 1002)

No app is allowed to synthesize keystrokes into itself through System Events. The paste silently fails. The user sees a stray "Copied! Press ⌘V to paste" toast they never asked for. It looks broken.

This bug has been in the Carbon code since day one. It's just that nobody ever deliberately sits in QUICOPY's own popover and hits a bound shortcut. I found it because the regression matrix includes that exact case.

I fixed it in two places, because Carbon and NSEvent reach the self-paste code path through different doors:

NSEvent local monitor intercepts key events that are dispatched inside QUICOPY. Instead of firing the mapping and letting it fail downstream, I just swallow the event at the monitor layer:

private func handleLocalKeyDown(_ event: NSEvent) -> NSEvent? {
    if isRecordingSuspended { return event }
    if matchMapping(event) != nil {
        // Popover is frontmost; don't trigger, don't beep, don't paste to self
        return nil
    }
    return event
}

AppDelegate.handleTriggered is the universal junction the Carbon callback also goes through. I added a frontmost check there as a second layer:

private func handleTriggered(_ mapping: KeyMapping) {
    let frontBundle = NSWorkspace.shared.frontmostApplication?.bundleIdentifier
    let ownBundle = Bundle.main.bundleIdentifier
    let popoverShown = popover?.isShown ?? false

    if frontBundle == ownBundle || popoverShown {
        return   // self-paste would trigger error 1002, abort
    }
    // ... proceed to paste ...
}

The popoverShown check is load-bearing. NSWorkspace.frontmostApplication has an interesting property: when a menu-bar popover is displayed, frontmostApplication still returns whatever app was frontmost before the popover opened, not QUICOPY itself. I discovered this the hard way when the first version of my defense only checked frontBundle == ownBundle and still let the popover case through. Reading popover.isShown is the reliable way to detect "QUICOPY's UI is currently on screen."

Neither of those checks is elegant. But together they cover both Carbon (which doesn't distinguish foreground/background) and NSEvent (which does), and neither backend now produces the stray error 1002 → clipboardOnly → toast cascade.

The Shortcut Recorder Problem (And Why It Almost Bit Me)

QUICOPY has a "record a shortcut" UI, implemented with NSEvent.addLocalMonitorForEvents(matching: .keyDown) to capture whatever combo the user presses. Perfectly fine in isolation.

But the new NSEventHotkeyManager also uses addLocalMonitorForEvents to handle self-triggered shortcuts when the popover is frontmost. Two local monitors, same app, racing to consume the same keyDown. One of them wins, which one depends on registration order and call site — and Apple's docs don't guarantee ordering.

The fix is a shared isRecordingSuspended: Bool flag on the monitor. When the user opens the mapping edit screen and taps "record shortcut," MappingEditView.onChange(of: isRecordingShortcut) flips the flag on via a closure provider. The hotkey monitor's local callback short-circuits:

// In NSEventHotkeyManager's local monitor:
if isRecordingSuspended { return event }   // pass through untouched
if matchMapping(event) != nil {
    return nil                              // popover self-paste — swallow, don't trigger
}
return event                                // unrelated key — forward

The order in which the two local monitors fire no longer matters. If the shortcut recorder fires first, it captures the key and returns nil; my monitor never sees it. If mine fires first, the isRecordingSuspended check passes the event straight through and the recorder captures it. Either way, the user's recorded shortcut ends up in the recorder, not triggering a mapping.

The closure-provider pattern is worth flagging: I initially passed HotkeyMonitoring instances directly into MappingEditView. That worked until the backend swapped mid-edit (AX permission flipped while the edit screen was open), and the edit screen kept writing isRecordingSuspended to the old, now-stopped monitor. Passing a closure that resolves appDelegate.activeMonitor on every call instead of a captured instance reference made the whole chain swap-safe.

Why I Narrowed the Design for a Mac App Store-only Release

Three tiers on paper was intellectually satisfying. Two tiers in production is what QUICOPY actually runs. Here's why the simpler thing is the right thing for my distribution:

Constraint 1: MAS sandbox rejects CGEventTap.
Apple's Developer Forums have confirmed this across several macOS releases. There's no entitlement to request, no review workaround, no "just ask for Input Monitoring." CGEvent.tapCreate under com.apple.security.app-sandbox = true returns nil. If I shipped the three-tier code, the CGEventTap branch would be unreachable in every App Store build I'd ever produce.

Constraint 2: I'm not shipping a Developer ID notarized build.
Originally I'd kept the Developer ID target as an option for users who wanted the "best" experience — event-swallowing included. Maintaining two distribution channels for a solo-developer indie app, with different permission flows, different crash-report pipelines, different update mechanisms, and a marketing story that has to explain which version to download, turned out to be more work than the feature was worth. I scoped down to MAS-only.

Consequence: The entire CGEventTap branch is orphan code.
EventTapHotkeyManager, SandboxInfo runtime detection, the circuit-breaker, the generation token — all of it exists to serve a tier that will never run. Carrying it adds maintenance cost (tests, comments that reference non-existent types, code reviewers asking "why is there a fallback that can't trigger?") without buying anything.

Shipping the two-tier version in full means:

HotkeyMonitoring.start returns Void, not Bool. It can't fail-and-fall-through because there's nothing to fall through to.
chooseAndStartMonitor is a single if/else, not a factory array with a for loop.
Readers of the code see exactly two backends and one branch. The structure matches the runtime reality.

If I ever do re-introduce a Developer ID channel, I'll add the CGEventTap tier back then — along with the test matrix, the release pipeline, and the marketing copy that all go with it. Reintroducing a protocol member in Swift is a 10-minute mechanical change; scoping the whole effort correctly is the harder work. Keeping placeholder scaffolding around today doesn't reduce that cost materially.

The word I'd avoid here is "killed." Nothing was killed. The scope was narrowed to the distribution I actually ship, and the code now reflects that.

The Boring Problem of Entitlements

People get scared of new entitlements because they're scared of App Review.

For this migration, the entitlements file does not change at all:

com.apple.security.app-sandbox — already set for MAS target
com.apple.security.automation.apple-events — already set for pasting

NSAccessibilityUsageDescription is not required for QUICOPY today. AXIsProcessTrustedWithOptions(nil) performs a silent check that doesn't trigger the system permission prompt, and my UI routes the user to System Settings directly when they opt into the Zed-compatible mode. If your app calls any of the prompting variants of that API, you'll want to supply the usage string — but QUICOPY never does.

Hardened Runtime is already on (ENABLE_HARDENED_RUNTIME = YES) and requires no additional com.apple.security.cs.* exceptions for NSEvent monitors. I'd been paranoid about that for weeks before actually testing it. No exception needed.

What the Final Flow Looks Like

User launches QUICOPY
       │
       ▼
PermissionManager probes AX via AXIsProcessTrustedWithOptions(nil)
       │
       ▼
AppDelegate.chooseAndStartMonitor()
       │
       ├─ AX granted     → NSEventHotkeyManager starts
       └─ AX not granted → HotkeyManager starts (Carbon legacy)
       │
       ▼
User grants AX later → applicationDidBecomeActive → probeAccessibility() → $isAccessibilityGranted fires → chooseAndStartMonitor() re-runs → swap to NSEvent
       │
       ▼
User presses ⌘1 inside Zed's terminal
       │
       ▼ (with NSEvent backend)
Event captured via addGlobalMonitorForEvents BEFORE Zed's TerminalInputHandler sees it
       │
       ▼
KeyMapping matched → AppDelegate.handleTriggered
       │
       ▼
TextOutputManager writes text to pasteboard, then AppleScript:
  • Checks Edit→Paste enabled state
  • enabled → click menu item "Paste"
  • disabled / absent → fallback to keystroke ⌘V
       │
       ▼
Text appears at the cursor inside Zed's terminal

The bottleneck in the chain is the clipboard → AppleScript round-trip. Hotkey capture itself is negligible on any backend.

What I'd Tell You If You're Building Something Similar

Don't start with Carbon. It's tempting because it's the zero-permission path. But in 2026, "zero permission" means "silently broken in a growing list of self-drawn apps." Budget an AX permission request into your onboarding from day one.
Test in Zed, VS Code, and at least one Electron/Tauri app. NSTextView-based apps will always work. Self-drawn UIs are the canary.
Pick your distribution channel before you pick your hotkey API. MAS-only means you can't use CGEventTap, full stop. Developer ID gives you that option but costs you a separate release pipeline. Decide first, architect second.
Subscribe to AX permission changes. applicationDidBecomeActive + AXIsProcessTrustedWithOptions(nil) is the closest macOS gives you to a "permission flipped" signal. There's no proper notification API.
Don't trust "AppleScript didn't throw" as "paste succeeded." In self-drawn hosts, click menu item can claim success on a menu that doesn't actually route to the focused view. Check enabled explicitly and keep a keystroke fallback.
Two local monitors on the same keyDown is a race. Use a shared suspended flag, not priority ordering. The recorder UI and the hotkey monitor cannot both assume they go first.
Check popover.isShown when defending against self-paste. NSWorkspace.frontmostApplication won't tell you that a menu-bar popover is currently visible; it still reports the app underneath.

Meta: Two Posts, Two Sides of the Same Wall

If you read the previous post, you have the full story now:

Output side: CGEvent.post() is blocked by sandbox. Workaround: clipboard + AppleScript System Events, with menu-enabled checks for self-drawn hosts.
Input side: Carbon RegisterEventHotKey is blocked by self-drawn frontmost apps. Workaround: upgrade to NSEvent global monitor whenever Accessibility is granted; keep Carbon as the zero-permission fallback.

Both problems stem from the same underlying fact: macOS's global-shortcut APIs were designed when the frontmost app was always an AppKit app with an NSTextView in it, and always happy to let the OS see events it didn't care about. That world is gone. Zed, VS Code, Warp's Rust UI, Flutter desktop apps, every Electron app with a canvas text surface — they all break the old assumptions, each in their own way.

What you ship for this class of problem is not a single API choice. It's an adaptive architecture that picks the right tool for the permission and distribution channel you're actually in.

About QUICOPY

I build QUICOPY — a macOS menu bar app that turns global shortcuts into instant text output, with 7 built-in AI prompt templates. It's on the Mac App Store for $9.99 lifetime or $1.99/month with a 7-day free trial.

If you want to see how all the pieces in this post ship in a real app, grab the binary.

Questions, corrections, or better approaches? Especially interested in hearing from anyone building non-AppKit macOS apps who has opinions on whether Carbon should finally be retired, or whether GPUI / Flutter should be patched to forward unhandled keys upstream. I don't think either fix is coming. So here we are.

Originally posted on quicopy.com. Follow me for more macOS indie dev notes.

Shipping Global Keyboard Shortcuts on macOS Sandbox: The Part Apple Doesn't Document

QUICOPY — Sat, 18 Apr 2026 14:49:56 +0000

TL;DR

I shipped a macOS menu bar app (QUICOPY) to the Mac App Store. Its core feature is global keyboard shortcuts that output text in any app. The obvious implementation — CGEvent.post() — is silently blocked by App Sandbox. Apple does not document this clearly. Here's what actually works, and why.

If you're building anything that simulates keyboard input on macOS and targeting the App Store, this will save you a week.

The Problem

I wanted a menu bar app where pressing ⌘⇧1 in any application types a piece of pre-set text at the cursor. TextExpander-style. Simple, right?

Two subproblems:

Capture a global keyboard shortcut (even when my app is not focused)
Output text into whatever app is focused

Both sound like 10-line solutions. Neither is, if you want to be on the Mac App Store.

Capturing Global Shortcuts: CGEvent Tap

This part is mostly fine. Use CGEvent.tapCreate with .cgSessionEventTap and listen for .keyDown events.

let eventMask = (1 << CGEventType.keyDown.rawValue)
let tap = CGEvent.tapCreate(
    tap: .cgSessionEventTap,
    place: .headInsertEventTap,
    options: .defaultTap,
    eventsOfInterest: CGEventMask(eventMask),
    callback: { _, type, event, _ in
        // Inspect event.flags and keycode here
        return Unmanaged.passUnretained(event)
    },
    userInfo: nil
)

Sandbox gotcha: CGEvent.tapCreate requires the user to grant your app Input Monitoring (or in some cases Accessibility) permission. This is fine — you get a permission prompt, user approves, done.

✅ This part works in a sandboxed Mac App Store app.

You can monitor events at the session level as long as the user grants the permission. The permission is called "Input Monitoring" in macOS 10.15+ and it specifically covers event taps.

No entitlement file magic needed for input monitoring — the sandbox allows the system permission prompt to handle it.

Outputting Text: The Approach That Everyone Tries First

Naturally, you reach for CGEvent.post():

// Synthesize ⌘V
let src = CGEventSource(stateID: .combinedSessionState)
let cmdVDown = CGEvent(keyboardEventSource: src, virtualKey: 0x09, keyDown: true)
cmdVDown?.flags = .maskCommand
cmdVDown?.post(tap: .cgSessionEventTap)

Works flawlessly in a non-sandboxed development build. You celebrate.

Then you enable App Sandbox (required for App Store), run it, and... nothing happens. No error. No log. No permission prompt. The .post() call just silently does nothing.

The Undocumented Rule

CGEvent.post() is completely blocked inside App Sandbox. There is no entitlement that re-enables it. Apple will not provide one.

I spent two days reading every developer forum thread, every entitlement documentation page, every StackOverflow answer. The closest Apple documentation admits it is this line in the App Sandbox Design Guide, which you have to squint to find:

Sending synthetic events to other processes is disallowed.

That's it. One sentence. In a guide that most indie devs stop reading after the "Container Directory" section.

The workarounds I saw suggested online, which do not work:

❌ Adding com.apple.security.temporary-exception.user-interaction — deprecated, no longer honored
❌ Adding com.apple.security.device.input — wrong entitlement, not related
❌ Using HIDPostAuxKey — same sandbox rule applies
❌ Using IOHIDPostEvent — same
❌ Requesting Accessibility permission — has no effect on this

What Actually Works: AppleScript System Events

The workaround is to pretend to be an automation client and ask System Events (an Apple-signed helper) to type for you.

Strategy:

Write the text into the clipboard (NSPasteboard)
Send an AppleScript "System Events → keystroke ⌘V" via NSAppleScript
Restore the previous clipboard contents

func outputText(_ text: String) {
    let pb = NSPasteboard.general
    let savedItems = pb.pasteboardItems?.compactMap { /* snapshot */ }

    pb.clearContents()
    pb.setString(text, forType: .string)

    let script = """
    tell application "System Events"
        keystroke "v" using command down
    end tell
    """

    var error: NSDictionary?
    NSAppleScript(source: script)?.executeAndReturnError(&error)

    // Restore clipboard after a short delay (let the paste complete)
    DispatchQueue.main.asyncAfter(deadline: .now() + 0.1) {
        pb.clearContents()
        // re-write savedItems
    }
}

Required entitlement:

<key>com.apple.security.automation.apple-events</key>
<true/>

Required Info.plist entry (macOS 10.14+):

<key>NSAppleEventsUsageDescription</key>
<string>QUICOPY uses System Events to paste your shortcut text into the currently focused application.</string>

On first use, macOS shows the user a permission prompt:

"QUICOPY wants permission to control System Events."

User clicks Allow → done. Works for all subsequent invocations.

The Latency Trade-off

CGEvent.post() (if it worked) would be ~5 ms. The AppleScript round-trip is 40–80 ms on a modern M-series Mac, closer to 100 ms on Intel.

For a text-expansion use case, this is invisible to the user — it feels instant. The whole flow (user releases shortcut → text appears) stays under 100 ms on Apple Silicon, which is the human perception threshold.

If you need true sub-10-ms latency (game input, accessibility apps), App Store distribution is probably not your path. Direct notarized distribution outside the store lifts the sandbox and lets you use CGEvent.post() directly.

The Clipboard Restoration Problem

The paste trick mutates the user's clipboard. If you don't restore it, users will paste your shortcut text into their next real Cmd+V — very bad UX.

Naive fix:

let saved = NSPasteboard.general.string(forType: .string)
// ... do paste ...
DispatchQueue.main.asyncAfter(deadline: .now() + 0.1) {
    NSPasteboard.general.setString(saved ?? "", forType: .string)
}

Problem: clipboard can hold multiple representations — images, rich text, file promises. A .string(forType:) snapshot throws all of that away.

Better:

let items = pb.pasteboardItems?.compactMap { item -> NSPasteboardItem? in
    let copy = NSPasteboardItem()
    for type in item.types {
        if let data = item.data(forType: type) {
            copy.setData(data, forType: type)
        }
    }
    return copy
}

// ... paste ...

DispatchQueue.main.asyncAfter(deadline: .now() + 0.15) {
    pb.clearContents()
    if let items = items { pb.writeObjects(items) }
}

Iterate every NSPasteboardItem.types and copy the raw Data for each. Preserves everything including image clipboard, file references, and rich text.

The Timing Problem

If you restore the clipboard too fast, you restore before System Events has read it → the paste gets nothing.

If you restore too slowly, there's a visible window where the user's original clipboard is gone.

Empirical finding: 100 ms delay is safe on Apple Silicon. 150 ms on Intel. executeAndReturnError does not block until the paste is truly complete — it returns as soon as the AppleScript dispatch succeeds.

Do not rely on DispatchQueue.sync thinking it'll wait — it won't, the paste is asynchronous on System Events' side.

App Store Review Pitfalls

When I submitted to the App Store, the reviewer flagged Accessibility in my initial build. I had included Accessibility API calls as a fallback for when Automation permission wasn't granted.

Apple's position: If you can accomplish the task through a less-privileged mechanism (Automation), don't ask for the more-privileged one (Accessibility).

I removed all Accessibility code and replaced it with a non-blocking permission-request flow that only asks for Automation. Resubmitted. Approved.

✅ Lesson: Minimize entitlements. Each entitlement is a question the reviewer will ask "do you really need this?"

What the Final Architecture Looks Like

User presses ⌘⇧1
         │
         ▼
CGEvent Tap (captures system-wide keydown)
         │
         ▼
Match against user's shortcut mapping
         │
         ▼
Load text snippet → NSPasteboard
         │
         ▼
NSAppleScript: "keystroke v using command down"
         │
         ▼
macOS System Events types Cmd+V into focused app
         │
         ▼
Restore previous clipboard (100ms delay)

Total latency: ~80–100 ms on M-series.
Total code: ~200 lines Swift.
App binary size: 2.8 MB (no Electron).
App Store: approved.

If You're Building Something Similar

Read the App Sandbox Design Guide twice. The fine print matters.
Don't assume CGEvent.post works, even if your dev build works. Test with sandbox enabled early.
Snapshot clipboard as pasteboard items, not strings.
Add a permission request UI for com.apple.security.automation.apple-events. Without it, the AppleScript fails silently the first time.
Minimize entitlements. Every one is a review friction point.
Consider whether you really need App Store. Direct notarized distribution gives you more freedom but less reach.

About QUICOPY

I built QUICOPY — a menu bar app that does exactly what this post describes, plus 7 built-in AI prompt templates mapped to ⌘⇧1 through ⌘⇧7. It's on the Mac App Store for $9.99 lifetime or $1.99/month.

If you want to see the end result of all this sandbox wrestling, there it is.

Questions or corrections? Happy to discuss in the comments — especially interested in hearing from anyone who's found a way to make CGEvent.post() work under sandbox (I don't think it's possible, but would love to be wrong).

Originally posted on quicopy.com. Follow me for more macOS indie dev notes.