IOKit HID Input
Raw keyboard events from IOKit HID. Below AppKit, below NSEvent, below everything.
Questions this answers
- How to reduce keyboard input latency on macOS terminal
- Why does my terminal feel sluggish when typing fast?
- NSEvent keyboard latency versus raw HID input on macOS
- Lowest latency keyboard handling for macOS apps
How it works
macOS keyboard events normally travel through the IOKit HID driver, into the WindowServer, through the NSEvent dispatch queue, and finally into the application's run loop. Each hop adds latency, and the NSEvent queue batches events per run loop iteration. Chau7 registers a direct IOKit HID client callback for keyboard events, receiving raw key-down and key-up reports before they enter the WindowServer event stream.
The HID callback translates USB HID usage codes to terminal escape sequences on a dedicated high-priority thread, bypassing the main thread run loop entirely. Dead key composition, modifier state, and keyboard layout mapping are handled in this path using IOKit's own key-mapping tables, preserving correct behavior for international keyboards and IME input.
The result is that key events arrive at the PTY within microseconds of the hardware interrupt, rather than the 2-8ms typical of NSEvent-based input handling. For fast typists and latency-sensitive workflows like Vim or interactive REPLs, this eliminates the perceptible lag between keypress and screen update.
Why it matters
Input latency is the most noticeable performance characteristic of a terminal. Even a few milliseconds of extra delay between keypress and screen update creates a subtle but persistent feeling that the application is not keeping up. Chau7 reads keyboard events from IOKit's HID subsystem directly, bypassing the entire NSEvent queue. The overhead is sub-millisecond.
Frequently asked questions
Does IOKit HID input work with macOS accessibility features?
Yes. Chau7 falls back to NSEvent processing when accessibility keyboard features (Slow Keys, Sticky Keys) are enabled, since those features require WindowServer-level event transformation.
Is IOKit HID input compatible with third-party keyboard remappers?
Remappers like Karabiner-Elements operate at the IOKit driver level, below Chau7's HID client. Their key remappings are fully visible to Chau7's HID callback, so all custom key bindings work as expected.
Does this affect IME input for CJK languages?
IME input is handled through the standard NSTextInputClient protocol on the main thread. IOKit HID input handles only direct key events; when an IME is active, events are routed through the normal AppKit path to preserve correct composition behavior.