mousemaster

• A keyboard driven interface for mouseless mouse manipulation
• Heavily inspired by warpd and mouseable

Demo • Overview • Installation • Usage • Features • Configuration • Troubleshooting • Contributing

Demo

Hints Demo

mousemaster-demo.mp4

Hint Styling Showcase

Grid Demo

mousemaster-grid.mp4

Mouse Movements Demo

mousemaster-mouse-movements1.mp4

Overview

mousemaster allows you to control your mouse cursor using only your keyboard. It provides multiple navigation methods:

• Normal mode: Move the mouse cursor with keyboard keys (IJKL by default)
• Hint mode: Display labeled hints (letters/numbers) across the screen that you can select with keystrokes to instantly move the cursor to that location
• Grid mode: Divide the screen into a grid that you can progressively refine to narrow down to a specific area
• Screen selection mode: Quickly move between multiple monitors

All modes and key bindings are fully customizable through a configuration file.

Installation

1. Download mousemaster.exe (a portable executable) from the Release page, or build it from source.
2. In the same Release page, choose and download one of the existing configuration files:
   • neo-mousekeys-ijkl.properties (recommended): an IJKL configuration (see documentation)
   • neo-mousekeys-wasd.properties: a WASD configuration (see documentation)
   • warpd.properties: an HKJL configuration (see documentation)
   • mouseable.properties: another HKJL configuration (see documentation)
   • author.properties: an IJKL configuration designed to control everything with the right hand only (see documentation)
3. Place the executable and the configuration file of your choice in the same directory.
4. Rename the configuration file to mousemaster.properties.
5. Run mousemaster.exe: make sure to run it as administrator if you want the mousemaster overlay to be displayed on top of everything else.
6. Feel free to open a GitHub Issue or join the Discord if you need help creating your own configuration. If you have ideas for a better configuration that you would like to share, I'd love to hear from you.

Usage

Default Configuration (neo-mousekeys-ijkl)

The recommended configuration uses the following key bindings:

• Activate: Press leftalt + e or leftalt + capslock
• Deactivate: Press q or p
• Mouse movement: Use i (up), j (left), k (down), l (right)
• Mouse buttons: ; (left), rightshift (middle), ' (right)
• Grid mode: Press g
• Hint mode: Press f
• Screen selection: Press c

For a complete reference, see the neo-mousekeys-ijkl documentation.

Features

1. Key combination system: Supports complex key combinations including timed holds (e.g., "hold alt for 1 second"), sequential presses (e.g., "press then release alt, twice in a row"), and nested combinations (e.g., "hold alt while pressing A then B").

2. Mode-based architecture: Implements a mode system where each mode has its own key-to-command mappings and mouse settings. The default "idle-mode" represents the disabled state with no active key mappings.

3. Many-to-many command mapping: Supports multiple key combinations triggering the same command and single key combinations triggering multiple commands.

4. Multi-monitor support.

5. Grid navigation: Implements a grid-based cursor positioning system that can target either the active screen or the active window.

6. Hint-based navigation: Features a Vimium-style hint system that can target the active screen, active window, or all screens.

7. Key remapping system: Includes a way to remap keys and activate the remapping only in specific modes. For example, you can make it so pressing a single key is equivalent to sending the combo ⊞ Win + down arrow, which will minimize the current window.

8. Zoom functionality: Supports configurable zoom behavior per mode.

9. Application-specific configurations: Provides context-aware mode switching based on the focused application, allowing for application-specific behavior (e.g., disabling mousemaster shortcuts in games).

10. Live configuration: Implements automatic configuration reloading when the configuration file is modified.

11. Visual feedback system: Provides an optional mouse indicator that changes color based on cursor state (idle, moving, clicking, scrolling) and repositions to remain visible near screen edges.

12. Position history hints: absolute positions can be saved on the fly to make it possible to move the mouse to them later.

Configuration

mousemaster is highly configurable through its configuration file. The configuration file is automatically reloaded when saved. For a complete reference of all configuration concepts and options, see the configuration reference. The reference document covers key aliases, combos, modes, mouse properties, hint properties, grid properties, app aliases, position history, logging, keyboard layout, and more.

Troubleshooting

Common Issues

1. Overlay not visible in some applications:

   • Run mousemaster.exe as administrator to ensure the overlay appears on top of all windows

2. Keyboard layout issues:

   • If your keyboard layout isn't automatically detected, specify it in the configuration:

     keyboard-layout=us-dvorak

     See Keyboard layout for more details.

3. Conflicts with other applications:

   • Create app-specific modes to disable mousemaster in certain applications:

     app-alias.gameapp=game.exe
     idle-mode.to.game-mode=_{gameapp}
     game-mode.to.idle-mode=^{gameapp}

     See App aliases for more details.

Contributing

Contributions to mousemaster are welcome!

• Share a configuration: If you have ideas for a new or improved configuration that you would like to share, open an issue or join the Discord.

• Cross-platform support: mousemaster currently supports Windows only. However, most of the overlay has been reimplemented using Qt, making it cross-platform-ready. The remaining work includes integrating support for global keyboard and mouse input handling and input simulation on macOS and Linux.

  If you're interested in helping extend mousemaster to these platforms, your contributions are very welcome. Please open an issue or join the Discord to get involved.

If you enjoy mousemaster, consider making a donation or stop by the Discord to show your support!