App conflicts & compatibility

General hotkey conflicts (blocks or triggers)

If Mouseless blocks or triggers hotkeys for another app, or vice versa, changing the order they are launched in may help, or simply adjusting the keybindings in one app or the other.

On macOS, changing the event tap location may also alleviate these conflicts. It’s in the System / debug section at the bottom of the config editor.

Workarounds for particular apps are in App-specific solutions below.

Programmatic invocation

Rather than resolving a hotkey conflict, you can sidestep it: Mouseless commands can be triggered by url instead of by hotkey, from any app or script that can open one. See Deep links.

Unexpected triggering of tap commands

In some cases, Mouseless tap commands (e.g. show overlay) are triggered because another app’s hotkey blocks certain (but not all) keystrokes from reaching Mouseless.

If you experience such issues, lowering the tap_threshold setting might help prevent false triggers.

Karabiner example / explanation:

• alt+F is assigned an action in Karabiner
• Alt tap is assigned to show overlay in Mouseless
• User presses alt+F quickly
• Karabiner allows the alt press and release through, but blocks the F press and release
• Mouseless sees an Alt tap (because it has no visibility of the F key events) and displays the overlay

Linux input mechanics

On Wayland, Mouseless uses evdev to exclusively grab the keyboard devices, and re-emits any events that shouldn’t be suppressed through a uinput virtual device.

If another tool already has an exclusive grab on all of your keyboards, Mouseless will show a “Keyboard Capture Failed” dialog listing the process(es) holding the devices. Launching Mouseless before that tool (or stopping the tool first) usually resolves this.

Exclude Mouseless virtual devices from other tools

All of Mouseless’s virtual devices carry the Sonuscape USB vendor id 0x736e so other input tools can identify them.

Exclude devices (virtual or real) from Mouseless

To prevent Mouseless from grabbing devices, add them to the excluded input devices field in the settings window (under keyboard layout in grid options). Run Mouseless with the --list-input-devices CLI flag to view device names/ids.

App-specific solutions

AutoHotkey

To use a Windows key tap without triggering the start menu, use this: ~LWin::vkE8 (see reddit thread)

BetterTouchTool

If you’re having issues with BTT hotkeys erroneously triggering the Mouseless overlay, a user has kindly provided this config / example, which may help you keep the same BTT hotkey, but without triggering Mouseless.

keyd

You must tell keyd to not grab Mouseless’s virtual device. Otherwise a feedback loop is formed, and the keyboard becomes unresponsive until one of them is killed. Exclude the Sonuscape vendor prefix in your keyd config:

[ids]

*
# Exclude Mouseless virtual devices via vendor prefix
-736e

[main]
...