Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Troubleshooting

Debug modes

Running Mouseless from the command line with certain flags provides extra visibility into what’s happening under the hood.

-d or --debug: enables verbose debug output, visible in both the log file and the terminal.

-p or --print-hid-events: prints keyboard input and mouse output to the terminal (not logged to file). To prevent accidental exposure, the printing will automatically disable after 5 minutes. This mode gives visibility into whether Mouseless is receiving certain keyboard events and how it’s interpreting them.

Examples:

macOS

open -W --stdout $(tty) --stderr $(tty) --stdin $(tty) /Applications/Mouseless.app --args -d

Windows (using PowerShell)

Single-user install (the default):

& "$env:LOCALAPPDATA\Programs\Mouseless\mouseless.exe" -d

All-users install:

& 'C:\Program Files\Mouseless\mouseless.exe' -d

Linux

flatpak run net.sonuscape.mouseless -d

Conflicts with other utility apps

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.

Other app-specific workarounds follow in the sections below.

Mouseless can handle ‘deep links’ (an app-directed url, e.g. mouseless://toggle-overlay). This can allow you to avoid conflicts with global hotkey handling between Mouseless and other apps.

Currently there are eight commands:

  • toggle-overlay, show-overlay, hide-overlay
  • toggle-free-mode, enter-free-mode, exit-free-mode
  • toggle-enabled, settings

Callbacks will be added soon so Mouseless can notify other apps when a mode is exited or a command is finished.

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

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.

macOS

CLI Security Advisory

On macOS, the only recommended way to run Mouseless from a terminal is with the open command, e.g.:

open -W --stdout $(tty) --stderr $(tty) --stdin $(tty) /Applications/Mouseless.app

Important: If you have ever run the internal binary directly (e.g. /Applications/Mouseless.app/Contents/MacOS/mouseless), please ensure you have revoked the Accessibility permission from your terminal app, otherwise any program launched from that terminal could potentially read screen content or log keystrokes.

To check your settings:

  • Go to System Settings > Privacy & Security > Accessibility.
  • Review the list. If your terminal application (e.g., Terminal, iTerm2) is present, select it and click the minus (-) button to revoke the permission.

Startup issues: No windows or status icon visible, or hotkeys don’t work

If you ever encounter these startup issues, these steps have proven to help in most cases:

  1. Exit Mouseless (via Activity Monitor if status icon is not visible)
  2. Go to System Settings > Privacy and Security > Accessibility
  3. Delete the Accessibility permission for Mouseless, if present
    • make SURE Mouseless isn’t running while you do this – MacOS tends to lock you out of keyboard and mouse input if you delete this permission from a running process / active event tap
    • select Mouseless and click the - button
  4. Re-add the permission
    • Click the + button, add /Applications/Mouseless.app
    • Make sure Mouseless is toggled ON
  5. Restart Mouseless

Hotkeys stop working during app usage

This may happen due to MacOS getting stuck in ‘Secure Input’ mode. Check the Mouseless icon in the status bar – if there’s a lock icon on it, the system is in secure input mode.

Espanso has a good explainer on this issue, as well as some potential workarounds to get un-stuck (the last resort is to log out your MacOS user and log back in).

Password fields

The overlay (and keybindings involving printable characters generally) will not respond when in a password field or other field marked as sensitive. This is not a bug, but a result of MacOS’s ‘Secure Input’ mode, which prevents applications from reading keyboard input while in these fields. To continue using Mouseless, simply leave the field (e.g. by pressing Tab).

Windows

Overlay appears behind Taskbar, Task Manager, etc.

For Mouseless to show the overlay above Start Menu, task manager, etc., you must:

  • choose to install for ‘all users’
  • install to a privileged location like Program Files (default)

This requires admin privileges during the installation process only, not when actually running Mouseless.

The installer provides an option to uninstall other/prior installations at different locations, checked by default. Your user data is not affected by the uninstallation.

For the portable version or non-privileged install locations, Mouseless makes a best effort to show above the taskbar, but is not guaranteed to work in all situations.

Linux

Overlay / Mouse Position & Scale

Mouseless does its best to automatically account for system display scaling to determine overlay size/position and mouse locations. Some users however, may need to do make manual adjustments.

At the bottom of the config editor you’ll find these settings, and you can hover over their labels for full explanation of possible values.

  • Overlay scaling for fixing incorrectly sized or positioned overlays
  • Mouse scaling for fixing incorrect mouse click locations
  • Mouse screen offset scaling for fixing incorrect mouse click locations on multi-monitor setups (use ‘Mouse scaling’ for the leftmost monitor and this setting for the rest if needed)

Further, if you find that the overlay position needs manual adjustment, you can enter an offset in the debug options field, e.g. { “overlay_offset”: { “x": 100, “y”: -50 } }.

Overlay / Window rendering issues

Some graphics cards / environments have issues rendering webviews with transparency, or at all.

If you encounter issues with transparency, you can force Mouseless to use the cairo-backed overlay (default when NVIDIA GPU is detected):

  • cli arg: --overlay-renderer cairo
  • config debug_options field: { "overlay_renderer": "cairo" }

Note that the cairo-backed overlay does not yet have the following features: highlight_animation, dots and dashed grid_line_styles, and always_show_subgrid.

If windows appear blank and the overlay seems to not show at all, you can force DMABUF rendering to be false for webviews (default when NVIDIA GPU is detected):

  • cli arg: --use-dmabuf false
  • config debug_options field: { "use_dmabuf": false }