HotkeyClash

Product Introduction

1. Definition: HotkeyClash is an open-source macOS menu bar utility and keyboard shortcut scanner. It is a specialized diagnostic tool that analyzes the entire shortcut ecosystem of a Mac, identifying conflicting key combinations across applications, custom automation configurations, and system-level bindings.
2. Core Value Proposition: HotkeyClash exists to solve the critical problem of macOS shortcut conflicts by providing a single-scan analysis that reveals every keyboard shortcut collision. It answers the common user frustration of "why did the wrong app respond when I pressed a hotkey?" by definitively showing which applications are claiming the same key combination, preventing guesswork and lost productivity.

Main Features

1. Comprehensive Conflict Scanning: HotkeyClash performs a deep, unified scan across three distinct sources of keyboard shortcuts. It uses the Accessibility API to read live menu bar shortcuts from every running application, directly parses configuration files for Karabiner-Elements and skhd to include remapped keys, and queries the macOS Symbolic Hotkeys plist to account for all built-in system shortcuts. This single-pass scan generates a complete map of claimed shortcuts, instantly highlighting definite conflicts (two global hotkeys on the same combo) and potential conflicts (a global hotkey overlapping an app's menu shortcut).
2. Zero-Dependency & Privacy-First Design: The application is built entirely with native Apple frameworks, ensuring no reliance on external libraries. It operates with zero dependencies, requires no installation of supporting tools, and functions completely offline. Furthermore, it adheres to a strict privacy policy: no telemetry, no cloud connectivity, no user accounts, and no data collection, making it a secure choice for sensitive development environments.
3. Active Conflict Analysis & Reporting: After the scan (demonstrated in 3.2 seconds), HotkeyClash presents a clear, grouped report. Conflicts are listed by the specific key combination (e.g., ⌘⇧G), showing all claiming sources (e.g., "Raycast vs Finder"). It provides contextual details, such as identifying whether a shortcut is a global hotkey or a menu bar shortcut, and specifies the conflict type to guide the user's next steps. This transforms a vague problem into an actionable list.

Problems Solved

1. Pain Point: The primary problem is the silent failure and hijacking of keyboard shortcuts on macOS. Users running multiple power-user tools (e.g., Raycast, Alfred, BetterTouchTool, Karabiner-Elements, skhd, window managers) often experience situations where pressing a key combination yields an unexpected result, as macOS does not natively flag conflicts between third-party applications. HotkeyClash eliminates this guesswork.
2. Target Audience: This tool is essential for macOS power users, developers, system administrators, and creative professionals who customize their workflow with multiple automation and productivity applications. It is specifically valuable for users of Karabiner-Elements and skhd who need to ensure their custom key remaps and hotkeys don't collide with global app shortcuts.
3. Use Cases: Key scenarios include:
   • Diagnosing why a personal shortcut for a function like "Go to Folder" or a custom action suddenly stops working or triggers the wrong application.
   • Setting up a new Mac or installing a new batch of productivity apps and preemptively checking for conflicts.
   • Troubleshooting after updating an application or system, which may have altered shortcut registrations.
   • Validating a complex automation configuration that involves Karabiner rules alongside global hotkeys in apps like Raycast or Alfred.

Unique Advantages

1. Differentiation: Unlike shortcut viewers such as KeyCue or KeyClu, which merely display shortcuts for a single application, HotkeyClash's sole function is conflict detection. It uniquely scans running apps, automation config files, and system shortcuts in one pass, a capability not found in other maintained tools. It surpasses the obsolete ShortcutDetective (which only intercepted live keypresses) by providing a proactive, comprehensive scan and modern Apple Silicon & macOS Sequoia support.
2. Key Innovation: The core innovation is its multi-source scanning engine that aggregates shortcut claims from disparate layers of the macOS software stack. By combining Accessibility API polling with direct configuration file parsing (JSON/plist), it achieves a holistic view of the shortcut landscape that no other single, free tool offers. This technical approach makes it the definitive macOS shortcut conflict scanner.

Frequently Asked Questions (FAQ)

1. How does HotkeyClash find shortcuts that other apps miss? HotkeyClash goes beyond just checking running apps. It directly parses the configuration files for Karabiner-Elements (karabiner.json) and skhd (skhdrc), capturing custom key remaps that are never broadcast as menu shortcuts. It also reads the macOS system's Symbolic Hotkeys plist, ensuring shortcuts for Mission Control, Spotlight, and Screenshots are included. This triple-layer scan catches conflicts invisible to single-app viewers.

2. What is the difference between a global hotkey conflict and a menu shortcut conflict? A global hotkey conflict is when two or more applications have registered the exact same key combination to trigger a function from anywhere in macOS. This is a definite conflict, and the OS typically routes it to the last-registered app. A potential conflict occurs when a global hotkey from one app matches a menu bar shortcut of another app; this only triggers when the app with the menu shortcut is in the foreground. HotkeyClash distinguishes between these types in its report.

3. Can HotkeyClash help me fix my shortcut conflicts? HotkeyClash is a diagnostic tool, not an editor. Its job is to clearly detect and report all keyboard shortcut conflicts. Once it shows you the conflicting key combination and the apps involved (e.g., "⌘⇧G: Raycast Search Snippets vs Finder Go to Folder"), you can then open the settings of one of those applications and reassign the shortcut to a different key combination. A quick re-scan with HotkeyClash will then confirm the conflict is resolved.