Skip to content

About

Find where your keyboard shortcuts clash. A free, open-source macOS menu bar app that detects shortcut conflicts across apps, config tools, and system settings.

Topics

Resources

Contributing

Security policy

Stars

235 stars

Watchers

1 watching

Forks

Repository files navigation

HotkeyClash

Find where your keyboard shortcuts clash.

macOS 14+ Swift 6.2 GPL-2.0 Zero dependencies

HotkeyClash - Find where your Mac keyboard shortcuts clash | Product Hunt

HotkeyClash scanning for shortcut conflicts

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.

Features

  • 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.

Install

Homebrew

brew install --cask wunderlandmedia/tap/hotkeyclash

To update later: brew upgrade --cask hotkeyclash.

Download

Grab the latest DMG or ZIP from Releases.

Build from source

git clone https://github.com/Wunderlandmedia/HotkeyClash.git
cd HotkeyClash
xcodebuild -scheme HotkeyClash -configuration Release build

Requires Xcode 16+ and macOS 14+.

Build a release (DMG + ZIP)

# Local build (skip notarization)
./scripts/build-release.sh --skip-notarize

# Full notarized release (after one-time Keychain setup)
./scripts/build-release.sh

Artifacts land in build/release/.

What it scans

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)

Which shortcut actually wins?

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.

Planned

  • 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.

Star History

Star History Chart

Also by Wunderlandmedia

  • QuietClip -- Privacy-first clipboard manager for macOS
  • WunderType -- AI text correction via keyboard shortcuts

Contributing

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.

License

GPL-2.0

About

Find where your keyboard shortcuts clash. A free, open-source macOS menu bar app that detects shortcut conflicts across apps, config tools, and system settings.

Topics

Resources

Contributing

Security policy

Stars

235 stars

Watchers

1 watching

Forks

Releases

Sponsor this project

Packages

Contributors

Languages