diagnose-dead-global-hotkey
Diagnose a Dead Global Hotkey
Self-Evolving Skill: This skill improves through use. If instructions are wrong, an API or app option changed, or a workaround was needed: fix this file and the scripts immediately, don't defer. Only update for real, reproducible issues.
A global hotkey works everywhere except while one app is in front (or full screen, or merely running). The press either does nothing or does something inside that app instead. This skill finds where on the input path the chord is lost or changed, then fixes that layer only.
The input path (bottom to top)
keyboard ─► DriverKit remapper (Karabiner-Elements) ─► HID tap point ─► Session tap point ─► hotkey dispatch ─► frontmost app
rewrites keys BELOW every tap active taps here can swallow or rewrite (Carbon RegisterEventHotKey)
tap-census.swift can also report taps at a third point, AnnotatedSession. The window server handles some shortcuts before events reach it (TigerVNC's source gives this as the reason it cannot grab the keyboard there), so a tap at that point is an unlikely culprit, and the logger does not watch it. If the four positions are all clean and the census shows an ACTIVE AnnotatedSession tap from the problem app, suspect it next.
Two facts drive the whole method:
- A remapper works below the tap layer. Karabiner's rules (for example a
frontmost_application_ifrule that turns Command into Control for a remote-desktop viewer) change the chord before any event tap, logger or hotkey sees it. - A synthetic test key enters above the remapper. A
CGEventPostprobe can report "hotkey fires" while the physical key still fails. Never conclude from a synthetic probe alone; confirm with a real key press in the logger.