Find where your keyboard shortcuts clash.
Open-source macOS menu bar utility that scans running apps, config files, and system shortcuts to detect keyboard shortcut conflicts. Master-detail split view shows every clash at a glance.
- Scans running apps' menu bar shortcuts via Accessibility API
- Parses Karabiner-Elements, skhd, Keyboard Maestro, BetterTouchTool, Hammerspoon, and Alfred configs
- Reads Obsidian's custom command hotkeys, which never show up in its menu bar
- Reads macOS system shortcuts (Spotlight, Mission Control, Screenshots, etc.)
- Reads shortcuts on macOS Services (Terminal's Open man Page, Make New Sticky Note, etc.)
- Classifies conflicts as definite (global vs global) or potential (menu vs menu)
- Tells you which shortcut most likely wins, based on where each one hooks the keyboard
- Watches a real keypress and reports which app actually caught it
- Search by app, action, or key combo (or narrow it with
key:u,app:finder,action:copy), and export the whole report as Markdown - 800x580 split view: conflict sidebar + detail pane with app icons and source badges
- Pin the panel open so it stays put while you go and fix the clash
- Reads Globe (fn) shortcuts, and lists its own hotkey rather than pretending it has none
- Zero external dependencies. Pure Apple frameworks.
brew install --cask wunderlandmedia/tap/hotkeyclashTo update later: brew upgrade --cask hotkeyclash.
Grab the latest DMG or ZIP from Releases.
git clone https://github.com/Wunderlandmedia/HotkeyClash.git
cd HotkeyClash
xcodebuild -scheme HotkeyClash -configuration Release buildRequires Xcode 16+ and macOS 14+.
# Local build (skip notarization)
./scripts/build-release.sh --skip-notarize
# Full notarized release (after one-time Keychain setup)
./scripts/build-release.shArtifacts land in build/release/.
| Source | Method |
|---|---|
| Running apps | Accessibility API (AXMenuBar traversal) |
| Karabiner-Elements | ~/.config/karabiner/karabiner.json |
| skhd | ~/.config/skhd/skhdrc |
| Keyboard Maestro | ~/Library/Application Support/Keyboard Maestro/Keyboard Maestro Macros.plist |
| BetterTouchTool | ~/Library/Application Support/BetterTouchTool/btt_data_store.* (SQLite, read-only) |
| Hammerspoon | ~/.hammerspoon/init.lua (hs.hotkey.bind calls) |
| Alfred | Alfred.alfredpreferences workflow info.plist hotkey triggers |
| Obsidian | <vault>/.obsidian/hotkeys.json for every vault in obsidian.json (in-app, not global) |
| macOS system shortcuts | com.apple.symbolichotkeys plist |
| macOS Services | com.apple.ServicesMenu.Services plus your overrides in pbs (works in any app, so it sits with menu shortcuts) |
A conflict list tells you two things claim the same keys. It does not tell you which one fires. HotkeyClash answers that by working out where each shortcut hooks the keyboard:
| Layer | Who is there | Sees the key |
|---|---|---|
| Driver | Karabiner-Elements | First, before macOS |
| Event tap | skhd, BetterTouchTool, Keyboard Maestro | Ahead of the system's own shortcuts |
| System | macOS symbolic hotkeys | Before any app-level hotkey |
| Global hotkey | Hammerspoon, Alfred, HotkeyClash itself | System wide, if nothing above took it |
| Menu item | The frontmost app | Last, and only when that app is focused |
The lowest layer usually wins, and that is the one HotkeyClash marks. When two tools sit on the same layer it says so instead of guessing, because the tiebreaker is registration order and no config file on disk records it.
Accessibility permission is required to scan running apps. Config files and system shortcuts work without it.
- Other command-palette apps that keep shortcuts outside the menu bar (VS Code next)
- Background monitoring: notice when another app steals a shortcut, without being asked
Raycast is not on the list. Its store is encrypted (SQLCipher, key in the login keychain) and its preferences carry no key data, so there is nothing a parser can read. The live keypress test is the honest answer for Raycast users.
- QuietClip -- Privacy-first clipboard manager for macOS
- WunderType -- AI text correction via keyboard shortcuts
Issues and pull requests welcome. Each config file parser is a self-contained method in ConfigFileScanner.swift, making it straightforward to add support for new tools.
