mousemaster

• Control your mouse from the keyboard and remap your keys, on Windows and macOS
• Heavily inspired by warpd, mouseable, neru and kanata

Demo • Install on Windows • Install on macOS • Usage • Features • Contributing

Demo

Hint grid

https://github.com/user-attachments/assets/cfba2c70-7edd-44bf-b63e-ded1613368da

UI hints

https://github.com/user-attachments/assets/ec6c7d45-da1e-43d1-82ba-76cef25dad6f

Recursive hint grid

https://github.com/user-attachments/assets/9140b3be-6109-4a90-a842-0a22c7e0e562

Recursive grid

https://github.com/user-attachments/assets/b395505e-9a06-4ec8-b361-81323c7b3fb4

Continuous mouse movement

https://github.com/user-attachments/assets/7300bf36-6a02-4615-b068-30c38571fc24

Installation

Windows

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)
   • neru.properties: a recursive hint configuration (see documentation)
   • neo-mousekeys-wasd.properties: a WASD configuration (see documentation)
   • warpd.properties: an HJKL configuration (see documentation)
   • mouseable.properties: another HJKL 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 mousemaster to draw 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.

macOS

macOS support is new and testers are wanted: if you try it, please report what does and does not work in an issue.

The setup below is more involved than it should be. mousemaster is not signed or notarized, which needs an Apple developer account I do not have, so macOS treats the app as unidentified and it has to be allowed by hand.

mousemaster reads the keyboard through the Karabiner virtual HID device, so that driver and a few permissions are needed.

1. Install Karabiner-Elements, which installs the virtual HID device, and allow its system extension when macOS asks.
2. Download and unzip mousemaster-macos.zip into /Applications:

   curl -L -o mousemaster-macos.zip https://github.com/petoncle/mousemaster/releases/latest/download/mousemaster-macos.zip
   unzip mousemaster-macos.zip -d /Applications
   

   Downloading it in a browser instead marks the app as quarantined, and macOS refuses to start a quarantined app that is not notarized. Clear it before the first run:

   xattr -dr com.apple.quarantine /Applications/mousemaster.app
   

   Or let macOS refuse it once, then allow it under System Settings > Privacy & Security > Security, where an Open Anyway button appears for it.
3. In the Release page, choose and download one of the configuration files listed above, place it in /Applications next to mousemaster.app, and rename it to mousemaster.properties.
4. Run it from a terminal, as root, which the virtual HID device requires. The configuration is read from the working directory, so start it from where you put it:

   cd /Applications && sudo mousemaster.app/Contents/MacOS/mousemaster
   

5. Grant the permissions macOS asks for, under System Settings > Privacy & Security. They are granted to the terminal you run mousemaster from rather than to mousemaster itself, so they survive replacing mousemaster.app with a new build. Quit and reopen that terminal after granting, then run mousemaster again.
   • Input Monitoring, to read the keys you press. Always needed.
   • Accessibility, only for UI hints (overlay.type=ui-accessibility).
   • Screen Recording, only for zoom (mode.zoom).

Usage

neo-mousekeys-ijkl configuration

• 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
• Recursive hint mode: Press r
• UI Hint mode: Press leftalt + ;
• Screen selection: Press c

For a complete reference, see the neo-mousekeys-ijkl documentation. The other configurations are documented too: neru, neo-mousekeys-wasd, warpd, mouseable, author.

Features

1. Combos and key remapping: Define combos (key sequences, chords, timed holds, taps, tap-dances, and more) to trigger commands, switch modes, or remap keys. See the combo reference.
2. Modes: Each mode has its own combos and its own overlay, indicator and zoom settings, and can inherit properties from other modes.
3. Conditional property values: Any mode property can take a different value depending on the current state: which keys are held, which app is active, what the mouse is doing, which screen the cursor is on, and more.
4. Continuous mouse movement: Move the cursor, click, scroll, and drag, all from the keyboard.
5. Hint navigation: Cover the screen with a grid of labeled hints, type a label to jump the cursor there.
6. UI hint navigation: Label buttons, links, and text fields in the active window.
7. Recursive grid navigation: Divide the screen into 2x2 sections, shrink with each key press or snap to the grid's edges to reach a precise position.
8. Zoom.
9. App-specific behavior: Restrict combos to specific apps, so the same keys behave differently depending on the focused app.
10. Indicator: Layers of shapes and text that show the mode and the state of the mouse. A layer goes at the cursor, in a corner of the screen, on the target or on the hints. Each layer has its own fill, stroke and shadow, and keyframes animate it.
11. Position history: Save cursor positions, jump back to them later. Keep several named histories, each with its own keys, and have a history hold a separate list of positions for each app.
12. Live configuration: All configuration lives in a single file that is automatically reloaded when saved.

mousemaster provides low-level primitives (modes, combos, commands, macros, key aliases) that you compose to build the exact behavior you want. See the configuration reference.

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 supports Windows and macOS.
  If you're interested in helping extend mousemaster to Linux, 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!