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

Customizing Mouseless

The config editor

  • To open the config editor, press Tab while the overlay is visible, OR choose Settings... 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
  • The config editor is searchable via ctrl+F (cmd+F on Mac)
  • To save, hit the save button (or press ctrl+S / cmd+S)
  • 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, the default config will be used the next time the app is started.

  • The location of the config file is:

    • Mac:
    ~/Library/Application Support/Mouseless/configs/config.yaml
    • Windows:
    ~/AppData/Local/Mouseless/configs/config.yaml
    • Linux:
    ~/.var/app/net.sonuscape.mouseless/data/mouseless/configs/config.yaml

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

General options

  • Automatically check for updates: When on, Mouseless checks for new versions daily and at startup.
  • Check for preview releases: When on, update checks include preview (prerelease) versions.
  • Hide welcome screen: Skips the welcome/tutorial window at startup.
  • Ignore update to version: Suppresses update notifications for the given version.

Keyboard options (currently shown in Grid section)

  • Keyboard layout: The keyboard layout used to interpret keys for the overlay and hotkeys, regardless of the current system layout.
  • Excluded input devices (Linux): Input devices Mouseless should never take control of. Matches by case-insensitive name substring, or by id (e.g. ids:046d:c52b; a 0 on either side acts as a wildcard). Run Mouseless with --list-input-devices to view device names/ids.

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. (with_mouse and with_keyboard_focus values not available on Wayland Linux).
  • 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.
  • Default action: The action (click, move, or drag) that execute mouse action performs in the default state (i.e. when no hold for or cycle command modifies it).
  • Mouse value cycle behavior: What happens to values set with the cycle button/action/count commands after a mouse action is executed.
    • once: the value returns to its default after executing an action.
    • persist: the value remains until cycled again.
  • Free mode after move: When on, free mode is entered after executing a move action from the overlay. See quick select + free mode.
  • 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

  • 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%).
  • Color input mode: The extra text input to show for editing color values. Note that rgb hex values (e.g. #ff0000) can always be copied/pasted while the color picker element is focused.

Background

See this youtube video for an explanation / demonstration of the multi-color system.

  • Background colors: The colors/opacities of the top-level cells, including underneath the highlight.
  • Color block size: Number of level 1 cells each background color is applied to, before cycling to the next. If set to 0, the colors are distributed evenly; e.g. if there are 30 top level cells and 3 colors, each color block will be 10 cells across.
  • Use color transforms Allows you to create variations of the base background colors across top-level cells, as well as create visually distinct regions within top-level cells.
  • BG Color Transforms - Level 1: Use these to transform the cells within each color block by adding or multiplying HSLA values (hue, saturation, lightness, alpha). Use “hsla_add” or “hsla_mult”, respectively. This can be convenient for distinguishing columns and/or rows within each color block. Editing the base background color(s) will shift all the transformed colors accordingly.
  • BG Color Transforms - Level 2: Use these to transform the background colors of 2nd-level cells. This allows you to create visual blocks within each top-level cell, e.g. to distinguish left hand keys from right hand keys in the subgrid, and/or top/middle/bottom keyboard rows.

Highlight

  • Highlight color: The color given to the currently active cell(s) of the overlay.
  • Highlight animation (ms): The time it takes (in milliseconds) for the highlight to move/scale to its new location and size. Set to 0 for instant movement.
  • 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 display: Controls which characters are shown in each cell.
  • Char anchor: Whether characters are spaced center-to-center (center) or edge-to-edge (edge).
  • 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.

HUD

  • Toast opacity: The opacity of the toast/status window, so it doesn’t overly obscure underlying screen content.
  • Free mode status display (Mac): How free mode status is indicated: toast, cursor (a dot indicator at the cursor; macOS 14+), both, or none.
  • Free mode indicator color / size / offset X / offset Y (Mac): The color, size (px), and position offset of the cursor dot indicator.

System / debug options

These are at the bottom of the config editor.

  • Event tap location (Mac): Where Mouseless inserts its event tap. Changing this may alleviate hotkey conflicts with other apps (see App conflicts).
  • Hud window level (Mac): The window level of Mouseless’ overlay/HUD windows. Adjusting this may fix issues when using software that captures displays (e.g. yabai).
  • Display input: Shows keyboard input on screen (for demos/troubleshooting). Resets to none on app restart.
  • Log level: Controls how verbose the log file is (debug, info, warning, error).
  • Overlay scaling / Mouse scaling / Mouse screen offset scaling (Linux): Manual corrections for display scaling issues – see Troubleshooting.
  • Debug options: A JSON object for less-common overrides – see Command line & debug options.