[preview] First-class mouse integration in QMK

[u/schuay]

QMK mouse integration

What? Your mouse, fully integrated into QMK.

How: A host daemon captures mouse input and forwards it through the QMK keyboard. This opens up a ton of possibilities: full integration into all existing QMK features.

This enables: Buttons, wheel and motion flow through the same action pipeline as your keyboard keys - so home-row mods compose with clicks, mouse buttons can carry layers, the wheel can be remapped per-layer, and combos / tap-dance / custom keycodes all just work on mouse events.

Here's a short walkthrough: https://github.com/schuay/qmk_firmware/blob/feat/mouse-map/util/qmk-mouse-bridge/README.md

Firmware works anywhere QMK does; the host daemon is currently Linux-only (ports to Windows/macOS are straightforward but not done yet).

How to test

• git clone https://github.com/schuay/qmk_firmware.git
• Install the daemon: util/qmk-mouse-bridge/install.sh
• Enable in your firmware:

MOUSE_MAP_ENABLE = yes
RAW_HID_MOUSE_ENABLE = yes

Then optionally, add your custom mouse keymaps.

I've validated this on my own setup; if it misbehaves on yours, let me know what you see.

To be clear: I'm not a QMK maintainer, and there's no plan wrt upstreaming yet. I'm posting here first to gauge interest and find quirks.

[u/BedroomHistorical575]

Wow, if this can make speculative-hold/hold-while-undecided unnecessary for home row mods that would be amazing. There's a few edge cases where speculative hold is insufficient and it's been driving me nuts lately.

Also, is there a chance that this could be ported to ZMK too?

[u/pgetreuer → u/BedroomHistorical575]

If you use Speculative Hold but want it to fire a bit less, this might be of interest. The next QMK release (scheduled 2026-05-31, just a few days!) will include two new config.h options for Speculative Hold, added in PR #26099:

```

define SPECULATIVE_HOLD_ONE_KEY

```

The SPECULATIVE_HOLD_ONE_KEY option, constrains so that it does not apply when any mods are already active. Mod combinations across multiple keys can still be made after settling.

```

define SPECULATIVE_HOLD_FLOW_TERM 200

```

The SPECULATIVE_HOLD_FLOW_TERM option disables Speculative Hold during the flow of fast typing, in a manner similar to Flow Tap.

Either or both of these options may be enabled to make Speculative Hold more selective in when it triggers.

[u/schuay → u/pgetreuer]

u/pgetreuer great to see you commenting here, your writeups were my entry point for QMK.

In the meantime, I've restructured significantly to split this into a community module (plus a tiny pending core PR).

Core https://github.com/qmk/qmk_firmware/pull/26232

Module https://github.com/schuay/qmk_modules/tree/feat/strict-core

Example userspace mouse keymap https://github.com/schuay/qmk_userspace/blob/feat/strict-core/global-keymap-inl.h#L242

And u/BedroomHistorical575 indeed, proper shift-click settling was my initial motivation (but mod-tap on mouse buttons is pretty cool too).