macos-global-shortcuts

macOS Global Shortcuts

Add keyboard shortcuts that work — in-app ones through SwiftUI, global ones through a real hotkey registration — and keep them configurable, disableable, and out of the system's way.

When to use

Use this skill when the user says:

• global shortcut / global hotkey
• keyboard shortcut that works everywhere
• summon the app / toggle the popover from anywhere
• quick capture hotkey
• ⌥Space / hyper key
• RegisterEventHotKey
• KeyboardShortcuts (the package)
• shortcut recorder / customize shortcuts
• shortcut conflicts

Do not use this skill for menu-item shortcuts inside a single window (that's plain .keyboardShortcut), or for intercepting/remapping other apps' keys (that's an event tap + Accessibility permission — a different, heavier topic).

Core rule

In-app shortcuts by default; global only for actions that must work
while the app is in the background. Every global shortcut is
user-changeable, disableable, and never a common system chord.

Decision tree

Does the action only matter while the app is frontmost?
  yes → SwiftUI .keyboardShortcut / menu commands. Stop here.

Must it fire while another app is focused?
  yes → global hotkey:
        indie/product app → KeyboardShortcuts package (recorder UI included)
        zero-dependency   → Carbon RegisterEventHotKey (old API, still correct)

Do you only need to OBSERVE keys, not own a chord?
  → NSEvent.addGlobalMonitorForEvents — but it can't consume events
    and needs Accessibility/Input Monitoring approval. Almost never
    what a "global shortcut" task actually wants.

In-app shortcuts (the 90% case)

// On a control
Button("New Entry", action: newEntry)
    .keyboardShortcut("n", modifiers: [.command])

// As a menu command — visible, discoverable, remappable by the
// user in System Settings > Keyboard > App Shortcuts
.commands {
    CommandMenu("Capture") {
        Button("Quick Capture", action: quickCapture)
            .keyboardShortcut("k", modifiers: [.command])
    }
}