Introduction

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

It is currently available on MacOS (v14+, Apple Silicon) and Windows, and is coming soon to Linux (first X11, then Wayland), Intel Mac, and MacOS 13.

How to use these docs

The sidebar on the left provides a list of all chapters. If the sidebar is not visible, click the hamburger menu (☰) to show it.

The arrow buttons at the bottom of the page can be used to navigate to the previous or the next chapter.

The left and right arrow keys on the keyboard can be used to navigate to the previous or the next chapter.

Top menu bar

The menu bar at the top of the page provides some icons for interacting with the book.

IconDescription
Opens and closes the sidebar.
Opens the color theme picker.
Opens a search bar for searching within the book.
Instructs the web browser to print the entire book.

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

Pressing the search icon () in the menu bar, or pressing the S key on the keyboard will open an input box for entering search terms. Typing some terms will show matching chapters and sections in real time.

Clicking any of the results will jump to that section. The up and down arrow keys can be used to navigate the results, and enter will open the highlighted section.

After loading a search result, the matching 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 ChatGPT or other LLMs for interactive Q&A about Mouseless.

Getting started

MacOS

Note: Currently, Mouseless is available on Apple Silicon, MacOS 14 and up. Intel Mac and MacOS 13 support is scheduled for release by June 10th.

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

First time usage:

  • open Mouseless
  • read/agree to the terms of service
  • start trial or activate
  • enjoy!

Linux

X11 support is scheduled to release by June 10, 2025, and work on support for various Wayland compositors / environments will then begin.

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, choose Edit config... from the Mouseless menu in the status bar / system tray, OR press Tab (edit config command) while the overlay is showing.

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-action timeout threshold (renamed to multi-click threshold in preview)
    • 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 (in preview)

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), V (right), and C as if they were mouse buttons
  • to increase movement (or wheel) speed, use A, S, D, and F -- the more of them you hold, the greater the increase
  • to decrease movement (or wheel) speed, hold ShiftLeft

Global mouse buttons (beta)

Note: In v0.3, these are called Mouse buttons w/o overlay.

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)

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. ctrl+click for right click, cmd+click to open link new tab).

Note: currently, modifiers assigned to wheel-related hold for commands will prevent this, but this will be fixed soon.

Wheel / scrolling

Note: In v0.4 (currently in preview), wheel mode has been replaced by free mode, where M, ,, ., and / are the keybindings for wheel up/down/left/right. See here for the rest of the free mode instructions.

To use the mouse wheel, tap the OptionLeft key on Mac or ControlLeft key on Windows (toggle wheel mode command) to enter and exit wheel mode -- currently, this must be done without the overlay showing, but support for using wheel mode with the overlay showing will be added soon.

While in wheel mode, use J, K, L, and ; to scroll up/down/left/right, and hold CommandLeft to increase the speed (there is also a hold for speed decrease command). There are also fast, step (precise increment, responds to autorepeat when held), and step large commands, as well as 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 Wheel subsection of the Behavior section in the config editor.

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, choose Edit config... from the Mouseless menu (in the Mac menu/status bar, or Windows system tray), OR press Tab while the overlay is visible
  • 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 (in preview): 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.
  • Mouse action keys (in v0.3): The keys you press to select a cell. They get mapped to each level of the main grid, mapping to multiple rows if necessary.
  • Subgrid action keys (in v0.3): The keys mapped across the rows of the subgrid, that you can press to execute a mouse action.
  • 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 (in preview): 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. Note: This is a beta feature. Some bugs may be present.
  • Nudges per cell (in preview): 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 (in preview): Determines where mouse actions are executed (via execute mouse action) when no cell is selected. Note: the with_keyboard_focus option may not work correctly on MacOS at this time.
  • Grid action level (in preview): 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 (experimental): When this is on, the system cursor will smoothly move as you select a cell, following the virtual cursor.
    • Note: in v0.3, when input is entered quickly, this feature may cause mouse actions to execute along the movement path instead of the destination -- this should be fixed in the latest 0.4 preview version.
  • Multi-action timeout (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. Note: This is called Multi-click threshold in v0.4 preview.
  • Tap threshold (ms): For tap-triggered keybindings, this is the maximum time a key can be down before its no longer considered a tap.

Wheel mode ('Free mode' in preview):

  • 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 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.
  • Wheel mode auto off (seconds): If no scroll actions are done for this many seconds, free mode will turn off. Set to0 to disable.
  • Wheel easing factor (in preview): Controls the smoothness / acceleration of wheel movement. 0.05 = loose, 0.1 = natural, 0.2 = snappy, 0.4 = instant. Note: this is currently affected by screen refresh rate, but this will be fixed soon.
  • Base move speed (px) (in preview): The amount the mouse cursor moves each tick during move up/down/left/right commands.
  • Move speed multiplier (in preview): Movement speed is multiplied by this amount for each hold for speed increase hotkey held.
  • Movement easing factor (in preview): Controls the smoothness / acceleration of cursor movement. 0.05 = loose, 0.1 = natural, 0.2 = snappy, 0.4 = instant. Note: this is currently affected by screen refresh rate, but this will be fixed soon.

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 (in preview): The font used in the overlay. You can use the cycle font command to change this while the overlay is up.
  • Font weight (in preview): 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: it's recommended that you don't re-use the same key in both the mouse action keys and the keymap -- it could result in unexpected or confusing program behavior. In v0.4 preview: if a key is present in the overlay at the current grid level, as well as a keybinding here, 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 (in preview): 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 (in preview): When continuous mode is on, the overlay stays up after executing a mouse action.
  • Toggle continuous mode until closed (in preview): Continuous mode will be turned off after the overlay is hidden.
  • Cycle grid action level (in preview): Cycles the value of the Grid action level field.
  • Cycle font (in preview): Cycles the value of the Font field. Note: This may be removed once keyboard-based selection in dropdowns is improved and/or previewing of the overlay is implemented.

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 (in preview)

  • Subgrid nudge up/down/left/right (in preview): 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.
    • Note 2: This is a beta feature. Some bugs may be present.

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.

Mouse buttons w/o overlay (renamed to 'Global mouse buttons' in preview)

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

Wheel mode (renamed to 'Free mode' in preview)

  • Toggle wheel mode: Toggles wheel mode.
  • Enter wheel mode: Activates wheel mode.
  • Exit wheel mode: Deactivates wheel mode.
  • Hold for speed increase: Multiples the scroll speed by the wheel speed multiplier value. (In preview: the more keys assigned to this and held, the greater the increase.)
  • Hold for speed decrease: Divides teh scroll speed by the wheel speed multiplier value. (In preview: the more keys assigned to this and held, the greater the decrease.)
  • 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): Executes a very large wheel event, to move the scrollable view to the given edge.
  • Move up/down/left/right (in preview): Moves the system mouse cursor.

Troubleshooting

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 after upgrading

At least one user has reported the following fix after upgrading to a new version of Mouseless:

  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
    • 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 don't work after a while (e.g. after lock screen)

This may be caused by a few different issues, one of which is MacOS getting stuck 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).

This issue may be fixed / reduced in 0.4.0-preview.2, and it also has a button at the bottom of the config editor to check if the system is stuck in Secure Input mode.

SSL / Network proxies

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 these errors, while we explore ways to prevent this extra legwork.

  1. Obtain the custom cert (.pem) file from your IT department
  2. 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: $ REQUESTS_CA_BUNDLE=~/Library/Containers/net.sonuscape.mouseless/Data/cert.pem open Mouseless.app

Simplified process (in preview)

Starting in v0.4.0-preview.2, this process should be 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.

At least one user, however, has gotten stuck in a loop where the cert is requested every startup, even after added (see issue 285). I haven't been able to reproduce this, so positive or negative feedback on this feature is appreciated!

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.

Karabiner and other HID input-modifying apps

Apps that can prevent keypresses from being dispatched to the rest of the system (as Karabiner sometimes does when one of its keybindings is triggered) 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.

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

Note: In 0.4.0-preview.2 you can try changing the event tap location to see if this alleviates these conflicts. It also has a limited, privacy-conscious, display input mode that allows you to see which keyboard events Mouseless is receiving. Both of these options are found in the System / debug section at the bottom of the config editor.

Roadmap and Known issues

Note: This document is new as of June 17th. I still have to comb through some of the older issues to make the enhancements and issues lists complete.

- croian

Roadmap

June 2025

  • Intel Mac beta
  • Linux X11 alpha or beta
  • Tutorial videos
  • v0.4 release candidate (Mac and Windows) (June 24th)
  • v0.4 stable (June 30th)

July 2025

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

August 2025

  • v0.5 stable
  • Linux Wayland, compositor 2 (wlroots or Mutter)

September 2025

  • v0.6 preview

Key enhancements

v0.4 (in preview)

  • Allow one set of keys to work across input sources (language/layout) - #108
  • Allow user to choose font - #165
  • Separate overlay keys into two separate levels - #161, #38, #97
  • Fewer keypresses to execute action (grid action level) - #41
  • Keep overlay up after click (continuous mode) - #137
  • Option to make click action happen at system cursor - #89
  • Relative mouse movement (free mode) - #191
  • subgrid nudges for improved precision - #44

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

  • Wheel-related hold for commands prevent modifier clicks - #189
  • Non-printable and whitespace keys cannot be assigned to grid - #19
  • Keyboard navigation in config editor is limited
  • Global mouse button keybinding fields map to free mode buttons - #302
    • Workaround: manually edit these fields in the config file
  • \ char in overlay causes it to be unresponsive - #277
    • Workaround: use | instead
  • Modifier+click (with physical mouse) can cause keybindings to trigger if done fast enough - #305
  • Subgrid nudge (beta feature) mode gets stuck - #311

Windows

  • Some users have issues with blank windows - #310
  • Double/triple clicks require extra keypress - #301
  • Some keys don't work in keybindings - #300
  • Modifier tap hotkeys don't work in Jetbrains IDE - #306
  • Overlay doesn't work after screen is locked - #298
  • Free mode movement doesn't clamp to desktop edge - #313
  • At least one user gets erroneous network errors, prevents starting trial - #234

Mac

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

Issues in preview

  • Inconsistent double/triple click behavior in certain apps - #226
  • Global mouse buttons keybindings causes keypresses to be blocked that shouldn't be - #178
  • Crosses and dashed line styles not available

Fixed in preview

  • Excess memory usage after editing the config - #156
  • Overlay shows up when pasting into a password field - #189
  • Move system cursor with virtual can cause action to execute at incorrect location - #181
  • Shifted version of keys don't activate subgrid - #107
  • Option and Control shortcuts don't work on non-qwerty layouts - #93
  • repeat last action keybinding passes through to underlying app - #159

Possibly fixed?

  • Overlay not showing after computer is locked - #164