# How OpenSuperWhisper Implements Global Keyboard Shortcuts Using Modifier-Only Keys

> Discover how OpenSuperWhisper uses low-level event taps to enable global keyboard shortcuts with modifier-only keys like Left Command or Right Option. Trigger dictation effortlessly.

- Repository: [Starmel/OpenSuperWhisper](https://github.com/Starmel/OpenSuperWhisper)
- Tags: how-to-guide
- Published: 2026-07-07

---

**OpenSuperWhisper uses a low-level CGEvent tap to monitor system-wide modifier key state changes, allowing users to trigger dictation with standalone modifier keys like Left Command or Right Option without combining them with other keys.**

OpenSuperWhisper is an open-source macOS dictation application that enables hands-free voice input through global hotkeys. Unlike traditional keyboard shortcuts that require key combinations, the app supports **global keyboard shortcuts using modifier-only keys**—such as pressing Left Command or Right Option alone—to start and stop recording sessions. This implementation relies on Core Graphics event taps to capture system-wide modifier state changes, providing a seamless experience across all applications.

## Architecture of the Modifier-Only Hotkey System

The implementation consists of three tightly-coupled components working together to intercept and process modifier key events at the system level.

### ModifierKey Enum Definition

Located in [`OpenSuperWhisper/ModifierKeyMonitor.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/OpenSuperWhisper/ModifierKeyMonitor.swift), the **`ModifierKey`** enum defines every supported modifier key. It maps each key to its raw key-code, the corresponding `NSEvent` flag, and a human-readable name. This abstraction allows the system to identify specific physical keys independently of their symbolic meanings.

### ModifierKeyMonitor Event Tap

The **`ModifierKeyMonitor`** class creates a low-level **CG event tap** that listens for `flagsChanged` events from the system. When the selected modifier's flag changes, it fires `onKeyDown` and `onKeyUp` callbacks. The monitor runs at the session level (`.cgSessionEventTap`), ensuring it captures events globally regardless of which application is front-most, provided the user has granted **Accessibility** permissions.

### ShortcutManager Orchestration

The **`ShortcutManager`** class in [`OpenSuperWhisper/ShortcutManager.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/OpenSuperWhisper/ShortcutManager.swift) decides which trigger mode to use. When a user selects a modifier-only hotkey in the preferences stored in [`OpenSuperWhisper/Settings.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/OpenSuperWhisper/Settings.swift), the manager disables the standard `KeyboardShortcuts` registration and wires the monitor's callbacks to its own recording logic.

## Implementation Flow in ShortcutManager

The setup process begins in `ShortcutManager.setupRecordingTrigger()`, which coordinates between user preferences and the low-level monitor.

When a modifier-only key is selected, the flow works as follows:

1. The system reads the selected modifier from `AppPreferences.shared.modifierOnlyHotkey`
2. Standard keyboard shortcuts are disabled via `KeyboardShortcuts.disable(.toggleRecord)` to prevent duplicate handling
3. The monitor's callbacks are wired to `handleKeyDown()` and `handleKeyUp()` methods
4. The monitor starts listening for the specific modifier key code

```swift
let modifierKey = ModifierKey(rawValue: AppPreferences.shared.modifierOnlyHotkey) ?? .none
if modifierKey != .none {
    // Disable the regular shortcut that KeyboardShortcuts registers
    KeyboardShortcuts.disable(.toggleRecord)

    // Forward low‑level modifier events to the recording logic
    ModifierKeyMonitor.shared.onKeyDown = { [weak self] in self?.handleKeyDown() }
    ModifierKeyMonitor.shared.onKeyUp   = { [weak self] in self?.handleKeyUp()   }

    // Begin listening for flagsChanged events for the selected key
    ModifierKeyMonitor.shared.start(modifierKey: modifierKey)
}

```

## Low-Level Event Handling

The `ModifierKeyMonitor` processes raw Core Graphics events to detect modifier state changes.

### Capturing Flags Changed Events

The `handleFlagsChanged(event:)` method in [`ModifierKeyMonitor.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/ModifierKeyMonitor.swift) inspects each incoming `CGEvent` to determine if the selected modifier is pressed or released:

```swift
private func handleFlagsChanged(event: CGEvent) {
    let keyCode = UInt16(event.getIntegerValueField(.keyboardEventKeycode))
    guard keyCode == selectedModifierKey.keyCode else { return }

    let isPressed = event.flags.contains(selectedModifierKey.cgEventFlag)
    if isPressed && !isModifierPressed {
        isModifierPressed = true
        DispatchQueue.main.async { self.onKeyDown?() }
    } else if !isPressed && isModifierPressed {
        isModifierPressed = false
        DispatchQueue.main.async { self.onKeyUp?() }
    }
}

```

This approach distinguishes between different physical keys (e.g., Left vs. Right Command) by checking the specific key code rather than just the generic modifier mask.

## Recording Logic Integration

When the monitor detects a modifier press, the `ShortcutManager` executes `handleKeyDown()` to initiate dictation.

### Starting a Dictation Session

The `handleKeyDown()` method prepares the recording interface through `IndicatorWindowManager` and optionally supports "hold-to-record" mode:

```swift
private func handleKeyDown() {
    holdWorkItem?.cancel()
    holdMode = false

    Task { @MainActor in
        // Start a new dictation session
        let vm = IndicatorWindowManager.shared.prepare()
        vm.startRecording()
        self.activeVm = vm
    }

    // Optional “hold‑to‑record” arm
    if AppPreferences.shared.holdToRecord && activeVm == nil {
        let work = DispatchWorkItem { self.holdMode = true }
        holdWorkItem = work
        DispatchQueue.main.asyncAfter(deadline: .now() + holdThreshold, execute: work)
    }
}

```

The method cancels any pending hold work items, initializes the `IndicatorWindowManager` from [`OpenSuperWhisper/IndicatorWindowManager.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/OpenSuperWhisper/IndicatorWindowManager.swift), and begins recording immediately or after a threshold in hold mode.

## Summary

- OpenSuperWhisper implements **global keyboard shortcuts using modifier-only keys** through a Core Graphics event tap that monitors system-wide `flagsChanged` events.
- The **`ModifierKeyMonitor`** class in [`ModifierKeyMonitor.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/ModifierKeyMonitor.swift) handles low-level event capture, distinguishing between specific physical modifier keys using raw key codes.
- **`ShortcutManager`** in [`ShortcutManager.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/ShortcutManager.swift) coordinates between user preferences and the monitor, disabling standard shortcuts when modifier-only mode is active to prevent conflicts.
- The event tap runs at the **session level** (`.cgSessionEventTap`), requiring Accessibility permissions but providing truly global hotkey functionality across all macOS applications.
- Recording logic integrates with **`IndicatorWindowManager`** to provide visual feedback when dictation starts via modifier key presses.

## Frequently Asked Questions

### Why does OpenSuperWhisper require Accessibility permissions for modifier-only shortcuts?

macOS restricts low-level event monitoring to applications with Accessibility permissions. Because the `ModifierKeyMonitor` creates a `.cgSessionEventTap` to listen for `flagsChanged` events system-wide, the app must be granted Accessibility access in System Settings to intercept modifier key states regardless of which application is currently active.

### How does the app distinguish between Left and Right modifier keys?

The implementation uses raw key codes defined in the `ModifierKey` enum rather than generic modifier masks. Each physical key (Left Command, Right Command, Left Option, Right Option) has a unique key code. The `handleFlagsChanged(event:)` method compares the event's key code against the selected modifier's key code, ensuring specific physical keys trigger the action.

### What happens if both a regular shortcut and a modifier-only hotkey are configured?

The `ShortcutManager` prevents conflicts by disabling the standard `KeyboardShortcuts` registration when a modifier-only hotkey is active. In `setupRecordingTrigger()`, the code calls `KeyboardShortcuts.disable(.toggleRecord)` before starting the `ModifierKeyMonitor`, ensuring only one trigger mechanism handles the input at a time.

### Can the modifier-only hotkey work while other applications are fullscreen?

Yes. Because the `ModifierKeyMonitor` uses a session-level event tap (`.cgSessionEventTap`), it receives events at the system level rather than the application level. This allows the modifier-only global keyboard shortcut to function even when the user is working in fullscreen applications or apps that normally intercept standard hotkeys.