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

Mouseless is a productivity / utility app that allows users to efficiently control the mouse with just the keyboard.

How to use these docs

The sidebar on the left lists all chapters. Click the hamburger menu (☰) to show or hide it.

To navigate to the next or previous chapter, use the arrow buttons at the side or bottom of the page or the Left and Right arrow keys on the keyboard.

Top menu bar

IconAction
Toggles the sidebar.
Opens the color theme picker.
Opens the search bar.
Prints the entire book.

Tapping the menu bar will scroll the page to the top.

Press the S key (or click the search icon () in the menu bar), to open the search bar.

Results are shown in real time. The Up and Down arrow keys can be used to navigate the results, and Enter will open the highlighted section.

Matched search terms will be highlighted in the text. Clicking a highlighted word or pressing the Escape key will remove the highlighting.

Single-page view / AI-assisted help

To view the docs in a single page, click the print icon in the menu bar, then cancel the print operation.

The content can then be copied and pasted into any AI chat for interactive Q&A about Mouseless.

Getting started

MacOS

To install (or update):

  • Download the .dmg file from https://mouseless.click
  • Open the .dmg file
  • Drag Mouseless.app into the Applications folder
  • If updating: choose "Replace" instead of "Keep both" when prompted

You can also install in the terminal via Homebrew:

  • brew install --cask mouseless (stable channel)
  • brew install --cask mouseless@preview (prerelease channel)

First time usage:

  • Open Mouseless (e.g. via spotlight search)
  • Read/agree to the terms of service
  • Start trial or activate
  • Give Mouseless the Accessibility permission when prompted
  • Restart the application for permissions to take effect
  • Enjoy!

Windows

To install (or update):

  • Download the latest Windows installer (.exe) or portable (.zip) file from https://mouseless.click
  • Run the installer (or extract the .zip)

First time usage:

  • Open Mouseless, e.g. via the start menu if installed, or if using the portable, by running the mouseless\mouseless.exe file in the extracted folder/location
  • Read/agree to the terms of service
  • Start trial or activate
  • Enjoy!

Linux

The X11 Alpha is out! Track progress on Wayland support here.

To install:

  • From https://mouseless.click, download the .AppImage for your OS and architecture, and the corresponding .sha256sum file.
  • Verify the download integrity: sha256sum -c <file>.sha256sum
  • Make the AppImage executable: chmod +x <file>.AppImage
  • Run the application: ./<file>.AppImage
  • Start a trial or activate with a license key
  • Enjoy!

Not working right? See this section for troubleshooting common issues.

Using Mouseless

Note: these docs currently show the default keybindings. If a command is unassigned by default, the command name is used instead.

To view/edit the keybindings and other options, press Tab (edit config command) while the overlay is showing, OR choose Edit config... from the Mouseless menu in the status bar (Mac) / system tray (Windows) / window header bar (Linux).

The overlay

  • To show the overlay, tap the CommandLeft (AltLeft on Windows) key (show overlay command)
    • Note: this is a tap command by default, so you must press and release the key relatively quickly for it to register (< 0.2 seconds by default, see Tap vs keydown for more info)
  • To hide the overlay, without executing a mouse action, press the Escape key (hide overlay command)

Clicking, moving, and dragging

With the overlay

  • To click:

    • while the overlay is showing, type the two characters of any given cell to choose that cell
    • then press Space to click at the center of the cell, where the virtual cursor is (execute mouse action command)
      • OR press any character you see in a sub-cell to click at that sub-cell
    • you can press Space any time the overlay is up, e.g. before entering any characters, to click where the virtual cursor is

  • To right click:

    • hold the Shift key (CommandRight on Mac) key while pressing the final key of a click action (hold for right button command)
    • use the cycle mouse button command to choose right, then execute a mouse action

  • To use other mouse buttons, use the appropriate hold for command or the cycle mouse button, in the same way as described above for right clicking

  • To double-click or triple-click, either:

    • press the final key of a click action multiple times within the multi-click threshold
    • use the cycle click count command

  • To click-and-drag / drag-and-drop, use the hold for drag command, i.e.:

    • hold the AltLeft key (CommandLeft on Mac) key while pressing the final key to begin the drag
    • the overlay will remain up for you to choose the point you want to drag to or drop at
    • to release/drop, enter in a click-coordinate as normal
    • to drag to a point (without release/drop), hold the AltLeft key (CommandLeft on Mac) on the final press again
    • to cancel a drag (release at the system cursor), press Escape (release hold/drag command)

  • Click-and-drag alternative: you can also use the cycle mouse action command to set the action to be performed. During a drag, it cycles between drag and drop.

  • To move the mouse cursor:

    • tap AltLeft (OptionLeft on Mac) while the overlay is up (execute mouse move command)
    • hold the key assigned to the hold for move command during the final keypress of a a mouse action
    • use the cycle_mouse_action command to set the action to move

  • To repeat the last action executed, use the repeat last mouse action command

With free mode

Free mode allows for relative movement, with no overlay needed to move, click, or drag.

To activate free mode, use the enter free mode command or toggle free mode command (OptionLeft tap on Mac, ControlLeft tap on Windows).

To exit free mode, use the exit free mode or toggle free mode command.

By default, free mode turns off automatically after 10 seconds without usage (adjustable via the Free mode auto off (seconds) option; set to 0 to disable).

While free mode is on:

  • to move, use I, K, J, and L
  • to click or click+drag, use Space (left mouse button), R (right), E (middle), Q (back), and W (forward) as if they were mouse buttons
  • to increase movement (or wheel) speed, use S, D, and F -- the more of them you hold, the greater the increase
  • to decrease movement (or wheel) speed, hold A

Global mouse buttons

These commands execute mouse button presses without the overlay, typically with a mouse or other pointing device still controlling cursor movement.

Use cases include:

  • clicking while maintaining precise cursor position/movement
  • preventing/alleviating repetitive strain injury
  • user preference over other clicking mechanisms

To use these commands, in the Keybindings -> Global mouse buttons section of the config editor, assign a key or key combo that won't interfere with your regular keyboard usage. All five mouse buttons (left, right, middle, back, and forward) can be assigned to. After assigning, you should then be able to use keyboard keys as mouse buttons, without having to bring up the overlay or activate free mode.

Modifier + click (or other actions)

  • On Mac, modifier + clicks can be performed in both overlay and free mode contexts.
  • On Windows, this feature is planned for v0.5.
  • On Linux, currently they can be done in free mode only.

If a modifier key is held during a mouse action, and isn't assigned to a hold for command, a native mod+mouse event will be simulated (e.g. shift+click for selecting groups of items in file explorer).

Wheel / scrolling

To use the mouse wheel, tap the OptionLeft key on Mac or ControlLeft key on Windows (toggle free mode command) to enter and exit free mode.

While in free mode, use:

  • M, ,, ., and / to scroll up/down/left/right
  • S, D, and F to increase the speed (the more pressed, the greater the increase)
  • A to decrease the speed

There are also fast, step (precise increment, responds to autorepeat when held), and step large commands, and on Mac and Windows there jump to top/bottom/left/right to jump to the edge of a scrollable area.

To adjust scrolling speed / step sizes, as well as auto off duration, see the Free mode subsection of the Behavior section in the config editor.

See here for the rest of the free mode controls / capabilities.

Multiple monitor usage

  • To move the overlay between monitors, tap the ShiftLeft or ShiftRight keys while the overlay is visible.

  • To assign different grid configs to different monitors:

    • In the Grid Options section of the config editor, use the + and - buttons to add/remove grid configs
    • With monitor assignment mode set to auto, the first grid config will be assigned to monitors with a horizontal aspect ratio, and the second will be assigned to monitors with a vertical aspect ratio
    • For more customized assignment, set monitor assignment mode to custom, and use the custom monitor assignments field to assign grid_config names to specific monitors
  • To open the config editor, press the Tab key while the overlay is up (edit config command)
  • To close dialogs, tooltips, etc, press the the Escape key (close ui element command)

Customizing Mouseless

The config editor

  • To open the config editor, press Tab while the overlay is visible, OR choose Edit config... from the Mouseless menu in the status bar (Mac) / system tray (Windows) / window header bar (Linux),
  • Many tooltips are available for in-context guidance. To see them, hover over:
    • The label on many fields
    • Some built-in presets
    • The info icons next to some sections
    • The info icon at the bottom-left of the config editor
  • Changes you make are applied automatically
  • On Windows, the config editor is searchable via ctrl+F
  • To save, hit the save button (or press cmd+S on Mac)
  • To save/load presets, or restore saved or defaults use the kebab menus in the section/subsection headers
    • To update or delete a user preset, right-click it to show a context menu
  • To restored saved or default values for a single field, right-click the field to show a context menu
  • Use the kebab menu at bottom to import a config file, export a config file, or restore defaults for the entire config

Field editing tips

  • You can press Enter in a text field to make it validate / take effect. Leaving the text field with Tab or the mouse also works.
  • Colors can be copied and pasted (with ctrl+C and ctrl+V (command on Mac)) while focused, or by dragging and dropping from one to another. The copied format is hex (e.g. #4e6c95).

Manually managing config files

  • You can choose Open config folder from the Mouseless menu, and edit/duplicate/delete files at will. config.yaml is the one loaded at app startup.
    • NOTE: if the config.yaml file is removed, or modified in such a way that it has invalid syntax or values, the default config values will be used the next time the app is started.

NOTE: the information for each field that follows is largely the same as is found in the in-app tooltips

Grid (overlay) options

The dimensions and content of an overlay is determined by a 'grid config'.

  • To add or remove a grid config, use the + / - buttons under the lowest grid config.

Grid config fields:

  • Level _ columns: The number of cells across the X dimension at this level.
  • Level _ rows: The number of cells along the Y dimension at this level
  • Level _ keys: The keys you press to select a cell at this level. They wrap to multiple rows if necessary. Note: If left blank for level 2 or subgrid, the keys from level 1 will be used.
  • Always show subgrid: Shows a subgrid in every cell, all the time, which can make it easier to know ahead of time which sub-cell you'll want to click. This comes at the cost of more visual noise, however. Currently only available whengrid line style is set to lines.
  • Hold Subgrid Key For Nudge: When on, holding a subgrid key allows you to use the subgrid nudge commands to move the cursor, then release the subgrid key to execute the action.
  • Nudges per cell: Determines nudge size. I.e. if set to 4, then 4 nudges will move the cursor to the same point in next subgrid cell.

Monitor assignment fields:

  • Monitor assignment mode: Controls how grid configs are assigned to monitors.
    • auto: the first grid config gets assigned to horizontal monitors, and the second gets assigned to vertical monitors.
    • single: the first grid config gets assigned to all monitors.
    • custom: grid configs are mapped by name, via the custom monitor assignments field.
  • Custom monitor assignments: List of grid config names, separated by comma+space (e.g. A, B). The first is assigned to the primary monitor, the second to the second monitor, and so on.

Behavior options

Overlay / cursor:

  • Initial overlay monitor: The monitor that the overlay will appear on when shown.
  • Initial action location: Determines where mouse actions are executed (via execute mouse action) when no cell is selected.
  • Grid action level: Determines the grid level that mouse actions get executed at (i.e. how many keypresses it takes). Use the cycle grid action level command to change this value while the overlay is up.
    • subgrid: When a leaf cell is selected, a subgrid is shown and Subgrid keys are used to execute an action.
    • 2 or 1: When a cell at the given level is selected, a mouse action is executed immediately, at its center.
  • Hide cursor on click: When on, the cursor moves out of the way after a click is executed.
  • Hide location: The corner or edge of the clicked screen that the cursor will move to. You can choose any edge (top/bottom/left/right) or corner (top_left/top_right/bottom_left/bottom_right).

Movement / timing:

  • Move duration (ms): The time taken to move the mouse cursor during move and drag actions.
  • Move system cursor with virtual: When this is on, the system cursor will smoothly move as you select a cell, following the virtual cursor.
  • Multi-click threshold (ms): For double and triple clicks, this sets the maximum time that can pass between keypresses before it no longer triggers a native double or triple click.
  • Tap threshold (ms): For tap-triggered keybindings, this is the maximum time a key can be down before its no longer considered a tap.

Free mode:

  • Base move speed (px): The amount the mouse cursor moves each tick during move up/down/left/right commands.

  • Move speed multiplier: Movement speed is multiplied by this amount for each hold for speed increase hotkey held.

  • Movement easing factor: Controls the smoothness / acceleration of cursor movement. 0.1 = loose, 0.2 = natural, 0.3 = snappy, 0.9 = instant.

  • Base wheel speed: The amount scrolled each tick during wheel up/down/left/right commands. Measured in pixels on Mac, lines on Windows.

  • Wheel speed multiplier: This multiplier gets applied:

    • to the fast mouse wheel actions
    • when hold for speed increase is active
    • when multiple keys for the same direction are pressed.

  • Wheel easing factor: Controls the smoothness / acceleration of wheel movement. 0.1 = loose, 0.2 = natural, 0.3 = snappy, 0.9 = instant.

  • Wheel step size: The amount scrolled each time a wheel step command is executed.

  • Wheel step size large: The amount scrolled each time a wheel step _ large command is executed.

  • Free mode auto off (seconds): If no actions are done for this many seconds, free mode will turn off. Set to0 to disable.

Misc:

  • Send escape after global alt tap (Windows): Simulates a press of the Escape key after certain global commands (e.g. show overlay, enter free mode) are triggered by an AltLeft/Right tap. Helps to deactivate the focused app's menu bar (which typically activates when Alt is tapped).,

Style / Appearance options

Base:

  • Master opacity: Overall opacity of the overlay. Multiplicative with other opacities -- e.g. if master opacity is 0.5 and and background opacity is 0.8, the final background opacity will be 0.4 (40%).
  • Background color: The color/opacity of the background, including underneath the highlight.
  • Highlight color: The color given to the currently active cell(s) of the overlay.
  • Show initial highlight: When on, the highlight will be shown before any cells are selected, covering the entire overlay. Useful when background opacity is zero.

Grid:

  • Grid line style: Note: Currently, Always show subgrid is only available for the lines style.
  • Grid line width (px): Note: Subgrid lines use this value only if grid line style is dots, otherwise they are assigned 1.
  • Grid line color: The color/opacity of the main grid lines.
  • Subgrid line color: The color/opacity of the subgrid lines.

Text:

  • Font: The font used in the overlay. You can use the cycle font command to change this while the overlay is up.
  • Font weight: Controls the boldness/lightness of the text. The actual effect varies by font.
  • Y offset: Moves the text up/down, by an amount scaled to the font size. This helps correct positioning for fonts that are not vertically centered.
  • Font size multiplier: Scales the size of the characters within the main grid.
  • Subgrid font size multiplier: Scales the size of the characters within the subgrid.
  • Char spacing strategy: Sets how the spacing of characters within a cell is adjusted: cell_width_relative, font_size_relative, or evenly_spaced.
  • Char spacing cell width ratio: 0 -> characters will be approximately touching edge-to-edge 1 -> characters will be evenly spaced across cells
  • Char spacing font size ratio: 0 -> characters will be approximately touching edge-to-edge 1 -> characters will be about as far apart as an uppercase character is tall
  • Text color: The opacity value here gets applied to a layer with the text and text shadow combined, so that the shadow doesn't show through the text.
  • Subgrid text color: "The opacity value here gets applied to a layer with the text and text shadow combined, so that the shadow doesn't show through the text.
  • Text shadow rgba: The opacity value here is in addition to what gets applied by the text color opacity (e.g. if both are 0.5, the shadow opacity is effectively 0.25).

Cursor:

  • Cursor size: The size (width and height) of the virtual cursor, in pixels.
  • Cursor color: The color/opacity of the virtual cursor in its default state.
  • Cursor right button color: The color/opacity of the virtual cursor when hold for right button is active or cycle button has been used to set the button to right.
  • Cursor move color: The color/opacity of the virtual cursor when hold for move is active or cycle action has been used to set the action to move.
  • Cursor drag color: The color/opacity of the virtual cursor when hold for drag is active or cycle action has been used to set the action to drag.
  • Cursor other color: The color/opacity of the virtual cursor when not in one of the states above.

Keybindings / command reference

The Keymap section of the config editor allows you to customize program keybindings

A condensed form of much of this info is available in-app in the Keymap section's info icon tooltip.

Note: if a key is present in the overlay at the current grid level, as well as a keybinding in the keymap, the overlay will take precedence.

Key names

The key names used/accepted mostly follow web conventions, with some exceptions, and some allowances for aliases.

  • Printable non-whitespace characters just use the literal character
    • A through Z, 0 through 9, -=`[]\;',./
      • Note: the non-shifted version of non-alpha characters should be used (e.g. 1 instead of !), and the uppercase version of alpha characters should be used (A instead of a, to avoid ambiguity with modifier shorthands (upcoming feature))
  • Whitespace characters are named:
    • Space, Tab, Enter
  • Modifier keys
    • Allowed aliases:
      • Command/Cmd/Meta/Win/Gui
      • Alt/Option/Opt
      • Control/Ctrl
    • Left/right-specific, or universal versions
      • e.g. Shift, ShiftLeft, or ShiftRight
      • Note: side-specific modifier keys are not yet supported as modifiers, only as main keys.
  • Other named keys list
    • ArrowLeft, ArrowRight, ArrowUp, ArrowDown
    • Numpad0 through Numpad9, NumpadAdd/Subtract/Multiply/Divide/Decimal/Equal/Comma/Enter
    • F1 through F20, Fn
    • Backspace, Delete, Escape, PageUp, PageDown, Home, End, Insert
    • NumLock, CapsLock
    • ContextMenu, VolumeUp/Down/Mute
    • Lang1, Lang2, IntlYen (¥), IntlRo (ろ), IntlBackslash

Assigning multiple keybindings to a command

To assign multiple keybindings to a single command, separate them with , (note the space). E.g. Escape, CommandLeft tap.

Tap vs keydown

Actions can be triggered either by a keydown event, or by a tap -- a downstroke and upstroke of the same key within tap_threshold milliseconds, uninterrupted by other keys.

To specify a tap keybinding, simply add tap (with a space) after the keyname, e.g. CommandLeft tap. CommandLeft on its own as a keybinding will cause the action to be triggered on the key downstroke (which can make interaction a bit snappier).

Using modifiers as...modifiers

To add a modifier to a keybinding in the usual way (like it is used for cmd+C for copy, cmd+S for save, etc), put them before the main keypress with a +, e.g.:

  • cmd+Tab
  • cmd+Tab tap
  • cmd+alt+shift+ctrl+Tab

The same aliases (see Key names) are allowed as when the modifier is used as the main key.

Command reference

Note: This information is largely the same as the in-app tooltips when you hover over the command name.

Overlay

  • Show overlay: Shows the overlay.
  • Hide overlay: Hide the overlay, without executing any mouse action.
  • Move to next monitor: Moves the overlay to the next to the next monitor.
  • Move to previous monitor: Moves the overlay to the previous monitor.
  • Increase master opacity (currently Mac-only): Increases the master opacity value.
  • Decrease master opacity (currently Mac-only): Decreases the master opacity value.
  • Toggle overlay lock (beta): When locked, the overlay will not respond to keypresses, and keypresses will pass through to focused app. May be useful while editing the config. This is a beta feature, and not fully implemented -- some commands will still affect the overlay.
  • Toggle continuous mode: When continuous mode is on, the overlay stays up after executing a mouse action.
  • Toggle continuous mode until closed: Continuous mode will be turned off after the overlay is hidden.
  • Cycle grid action level: Cycles the value of the Grid action level field.
  • Cycle font: Cycles the value of the Font field.

Mouse actions

  • Execute mouse action: In the default state, executes a left click at the virtual cursor. Can execute other actions/buttons/click_counts if hold for or cycle commands are used. Double and triple clicks can be executed by pressing multiple times.
  • Execute mouse move: Moves the system cursor to the virtual cursor.
  • Undo last key: Undoes the last key when selecting a cell.
  • Release hold/drag: During a drag action, 'drops' at the system cursor.
  • Repeat last mouse action: Repeats the last mouse action, at the same location it was executed at.
  • Hold for move: When held, execute mouse action will move the system cursor to the virtual cursor.
  • Hold for drag: When held, execute mouse action will start (or continue) a drag operation (i.e. moving the mouse while mouse button is held down).
  • Hold for right/middle/back/forward button: When held, execute mouse action will execute a right/middle/back/forward click at the virtual cursor.
  • Cycle mouse action type: Sets the action (click, move, drag) that execute mouse action will trigger.
  • Cycle mouse button: Sets the mouse button (left, right, middle, back, forward) that execute mouse action will use.
  • Cycle click count: Sets the click count (single click, double click, triple click) that execute mouse action will trigger.

Subgrid nudge

  • Subgrid nudge up/down/left/right: These commands move the cursor when hold subgrid key for nudge is on and a subgrid key is held.
    • Note: If you use keys that are also present in the subgrid, you should give each command a key for the left hand and the right hand.

Dialog / menu

  • Edit config: When the overlay is up, opens this config editor.
  • Close UI element: Closes the currently open dialog, color picker, context menu, etc.

Global mouse buttons

  • left/right/middle/back/forward: These commands execute mouse button presses without the overlay, typically with a mouse or other pointing device still controlling cursor movement.
    • Use cases include:
      • clicking while maintaining precise cursor position/movement
      • preventing/alleviating repetitive strain injury
      • user preference over other clicking mechanisms
    • Note: On Mac, dragging and double/triple clicks may not work on some elements (but will be implemented very soon).

Free mode

  • Toggle free mode: Toggles free mode.
  • Enter free mode: Activates free mode.
  • Exit free mode: Deactivates free mode.
  • Hold for speed increase: Multiples the scroll speed by the wheel speed multiplier value. The more keys assigned to this and held, the greater the increase.
  • Hold for speed decrease: Divides the scroll speed by the wheel speed multiplier value. The more keys assigned to this and held, the greater the decrease.
  • Move up/down/left/right: Moves the system mouse cursor.
  • Wheel up/down/left/right: Executes smooth/continuous scrolling while held.
  • Wheel up/down/left/right fast: Executes smooth/continuous scrolling while held, with the wheel speed multiplier applied.
  • Wheel step up/down/left/right: Executes a discrete scroll event, the amount determined by the wheel step size setting. Responds to system 'autorepeat' when a key is held.
  • Wheel step up/down/left/right large: Executes a discrete scroll event, the amount determined by the wheel step size large setting. Responds to system 'autorepeat' when a key is held.
  • Jump to top/bottom/left/right edge (experimental) (Mac/Windows-only): Executes a very large wheel event, to move the scrollable view to the given edge.

Troubleshooting

Debug modes

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

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

-p: 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)

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

Linux

./<filename>.AppImage -d

macOS Input Issues

Important 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).

If you have ever run Mouseless from the terminal by executing the file inside the .app bundle directly (e.g. /Applications/Mouseless.app/Contents/MacOS/mouseless), please take a moment to ensure you have revoked the Accessibility permission from your terminal app(s). Leaving this permission enabled for a terminal app presents a security risk, as 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.

Password fields (MacOS)

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).

Hotkeys don't work on app startup

If you ever encounter an issue where hotkeys don't work on app startup, these steps have proven to help in most cases:

  1. exit Mouseless
  2. delete the Accessibility permission for Mouseless
    • 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
    • System Settings > Privacy and Security > Accessibility > select Mouseless and click the - button
  3. Re-add the permission (either via the + button or by restarting Mouseless)
  4. Restart Mouseless

Hotkeys stop working during app usage

There may be a chance that this happens due to MacOS getting stuck in 'Secure Input' mode. There is a Check Secure Input Status button at the bottom of the config editor to check if this is the cause.

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).

BetterTouchTool conflicts

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.

General conflicts with other keyboard utility apps

Apps like Mouseless, Karabiner, etc. can suppress keypresses from being dispatched to the rest of the system. Depending on the configuration of other apps, some hotkeys may cause Mouseless keybindings to trigger when not expected.

For example, if alt+F is assigned an action in Karabiner, and Alt tap is assigned to show overlay in Mouseless, karabiner might allow the alt press and release through to the rest of the system, but block the F press/release. If it's all pressed quickly enough, Mouseless might register this as Alt tap and display the overlay, as it has no visibility of the F key events.

If you experience such issues, lowering the tap_threshold setting might help prevent most false triggers, otherwise you might need to adjust keybindings in one app or the other.

On macOS, you can try changing the event tap location to see if this alleviates these conflicts. It's found in the System / debug section at the bottom of the config editor.

Windows Input Issues

Autohotkey

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

Linux - Common Issues

Blank Windows

This is likely the result of GPU/driver compatibility issues.

  • Solution: You can use the --no-compositing CLI flag or WEBKIT_DISABLE_COMPOSITING_MODE=1 environment variable to fix this
  • Side effect: When using this mode, the overlay may not clear its draw buffer correctly, causing highlights and subgrids to stay visible when they shouldn't. Background and highlights accumulate opacity, but typically clear approximately every 5 uses of the overlay.
  • Workaround: There is a minimal_background style preset that helps alleviate the opacity buildup side effect.

Segmentation Fault on Startup

Observed on Linux Mint 22: the app crashes with a 'segmentation fault' error in the terminal on startup.

  • Solution: You may find that installing proprietary drivers (as opposed to 'Mesa' drivers) solves the issue for you -- see this user-provided guide for more info / instructions.
  • Disclaimer: update drivers at your own risk. The creators of Mouseless are not liable for any issues that may arise from doing so.

Overlay Size

Mouseless does its best to automatically determine and account for system DPI scaling to correctly size and position the overlay(s). Some users however, may need to do one of the following:

  • Use the --dpi-scale CLI option to force a certain scale. The value is your system's DPI divided by 96 (the default). For example, for a system with 192 DPI, use --dpi-scale 2.0.
  • Use --dpi-scale 1 to counteract the effects of the automatic process

Mouse Position

If you find that mouse click positions don't line up with the overlay, you can currently use the debug options field (at bottom of config editor) to enter JSON to fix this (adjust values as needed):

{ "mouse_screen_position_mult": 1, "mouse_screen_size_mult": 1.25 }

SSL / Network proxies / Air-gapped machines

Mouseless must use the network to start a trial and to validate licenses (purchased licenses store an offline license that must be refreshed at least every 30 days -- the program attempts to do this automatically).

If you are behind a corporate proxy (or if you have a custom SSL certificate for other reasons) and are seeing SSL errors on startup, you can use the following procedure to fix to enable network connectivity.

  1. Obtain the custom cert (.pem) file from your IT department
  2. On macOS, move/copy the .pem file to the Mouseless data dir, e.g.: $ cp cert.pem ~/Library/Containers/net.sonuscape.mouseless/Data/
  3. Open Mouseless via the command line like so:
  • macOS
REQUESTS_CA_BUNDLE=~/Library/Containers/net.sonuscape.mouseless/Data/cert.pem open Mouseless.app
  • Windows (powershell)
$env:REQUESTS_CA_BUNDLE="path\to\cert.pem"; & 'C:\Program Files\Mouseless\mouseless.exe'
  • Linux
REQUESTS_CA_BUNDLE=path/to/cert.pem ./<filename>.AppImage

Simplified process

On some systems, this process is now greatly simplified: no more need to run from the terminal -- you will now be prompted to import the certificate on startup, and Mouseless should thereafter work whether you're on the network that requires the custom cert, or on a normal network.

Note: We're working to bring this simplified process to all systems.

Web interface / Air-gapped machines

We are also aiming to implement a secure web interface for generating an offline license file by the end of September, which will allow activation/validation on air-gapped machines, or can be used for SSL issues if a custom cert is not available.

Roadmap and Known Issues

Note: This document is relatively new and incomplete. Some time after the v0.4 stable release, I'll comb through the older issues to make the enhancements and issues lists more complete.

- croian

Roadmap

September 2025

  • Tutorial videos
  • Initial v0.5 preview
  • Linux Wayland, compositor 1 (wlroots or Mutter)

October 2025

  • Linux Wayland, compositor 2 (wlroots or Mutter)

November 2025

  • v0.5 stable

Key enhancements

v0.5 (upcoming)

  • Improved welcome / tutorial
  • Custom, separate background colors for top-level cells/rows/columns - #203
  • Customizable config location - #110, #187
    • Workaround: use a hard link: ln ~/.config/mouseless/config.yaml "$HOME/Library/Containers/net.sonuscape.mouseless/Data/.mouseless/configs/config.yaml"
  • Monitor selection improvements
    • Guaranteed left/right ordering - #133
    • Direct selection via hotkey - #324
    • Single overlay across multiple monitors
  • Zoom on subgrid for readability - #53, #320
  • Improved precision
    • Shift/case sensitive overlay keys
    • Additional grid level
  • Preserve comments and field order in config file - #129
  • Allow wheel movement while overlay is up - #194
  • New wheel-related hold for commands (hold for wheel mode, stepped scrolling)
  • Hide inactive portion of overlay - #261
  • Improved preset management - #303
  • Show status toast on active overlay/monitor - #318

Known issues

All platforms

  • Non-printable and whitespace keys cannot be assigned to grid - #19
  • Keyboard navigation in config editor is limited
  • Modifier+click (with physical mouse) can cause keybindings to trigger if done fast enough - #305

Windows

  • Some keys don't work in keybindings - #300
  • Modifier tap hotkeys don't work in Jetbrains IDE - #306

Mac

  • In Apple Music, some UI elements don't respond to overlay clicks - #167
  • In Jetbrains IDE, project tabs don't respond to overlay clicks - #293