Keyboard Shortcuts System
Relevant source files
The following files were used as context for generating this wiki page:
The Keyboard Shortcuts System in Buddi provides a centralized mechanism for managing user-defined hotkeys and system-level key commands. It integrates the third-party KeyboardShortcuts framework with native macOS Carbon and AppKit APIs to handle global event monitoring, UI-based shortcut recording, and the execution of specific application actions such as toggling the Notch interface or controlling media playback.
This system is essential for accessibility and productivity, allowing users to interact with Buddi's core features—including the Claude Code Integration and Notch Utility—without relying solely on mouse movements or hover gestures.
Sources: buddiApp.swift:207-248, README.md:37-45
Architecture and Key Components
The system is built on an extension-based architecture that bridges high-level SwiftUI views with low-level macOS event handling.
Global Event Monitoring
The BuddiApp delegate serves as the primary entry point for global shortcut registration. It uses the KeyboardShortcuts.onKeyDown API to listen for specific named shortcuts even when the application is not the active front-most window.
Sources: buddiApp.swift:207-248
Shortcut Helper Extensions
To maintain compatibility between modern SwiftUI modifiers and the underlying Carbon key codes, the system includes a helper utility that translates KeyboardShortcuts.Shortcut objects into SwiftUI-compatible KeyEquivalent and EventModifiers. This involves interacting with the Unicode Key Layout Data via UCKeyTranslate.
Sources: buddi/extensions/KeyboardShortcutsHelper.swift:11-73
The diagram shows the flow of a keyboard event from physical press to application state update.
Sources: buddiApp.swift:207-248, buddi/extensions/KeyboardShortcutsHelper.swift:11-20
Core Shortcuts and Actions
The application defines several critical shortcuts that facilitate quick interaction with the Buddi Notch and its background services.
| Shortcut Name | Internal Identifier | Default Action |
|---|---|---|
| Toggle Notch Open | .toggleNotchOpen | Toggles the visibility of the Buddi Notch on the current screen. |
| Toggle Sneak Peek | .toggleSneakPeek | Shows media title and artist information under the notch. |
| Settings | Command + , | Opens the Buddi Settings window. |
| Quit | Command + Q | Terminates the application. |
Sources: buddiApp.swift:42-55, buddi/components/Settings/SettingsView.swift:1078-1090, buddiApp.swift:207-248
Notch Visibility Logic
When the .toggleNotchOpen shortcut is triggered, the system determines which screen the mouse is currently on to target the correct BuddiViewModel. It cancels any pending auto-close tasks and toggles between the .open and .closed states.
Sources: buddiApp.swift:221-248
Media Control Modifiers
The system also handles media-specific modifiers through the OptionKeyAction configuration. Users can define what happens when the Option (⌥) key is held while pressing media keys, such as opening System Settings or showing the HUD.
Sources: buddi/models/Constants.swift:65-71, buddi/components/Settings/SettingsView.swift:513-520
Carbon to SwiftUI Translation
A sophisticated translation layer is used to convert low-level Carbon key codes into SwiftUI KeyEquivalent values. This ensures that shortcuts work correctly across different keyboard layouts.
Implementation Details: UCKeyTranslate
The system retrieves the current keyboard layout using TISCopyCurrentKeyboardLayoutInputSource and uses UCKeyTranslate to map the carbonKeyCode to a UTF-16 character buffer.
Sources: buddi/extensions/KeyboardShortcutsHelper.swift:34-53
This sequence illustrates the translation of hardware-specific key codes to application-level characters.
Sources: buddi/extensions/KeyboardShortcutsHelper.swift:34-55
User Configuration (Settings)
The Shortcuts section in the Buddi Settings window allows users to customize these hotkeys via a Recorder component.
- Customization: Users can rebind the "Toggle Sneak Peek" and "Toggle Notch Open" actions.
- Persistence: These shortcuts are persisted via the
Defaultssystem, ensuring they remain active across application restarts. - Accessibility: The settings UI provides context, such as explaining that the Sneak Peek shows media metadata for a few seconds.
Sources: buddi/components/Settings/SettingsView.swift:1078-1094, buddi/models/Constants.swift:74-175
Summary
The Keyboard Shortcuts System in Buddi acts as a bridge between the user's hardware and the application's Notch UI. By utilizing a translation layer that leverages Carbon APIs, Buddi ensures that global hotkeys are responsive and layout-aware. This system directly powers the application's ability to provide a "HUD replacement" and "Live session monitoring" by giving users immediate, keyboard-driven control over visibility and interaction states.
Sources: README.md:27-45, buddi/extensions/KeyboardShortcutsHelper.swift:11-20