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

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

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

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 yet, 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, so that mousemaster.app sits next to a mousemaster.properties:

   curl -L -o mousemaster-macos.zip https://github.com/petoncle/mousemaster/releases/download/nightly/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. 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
   

4. 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 (hint.type=ui).
   • Screen Recording, only for zoom (mode.zoom).

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
• UI Hint mode: Press leftalt + f
• Screen selection: Press c

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

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 hint, grid, indicator and zoom settings, and can inherit properties from other modes.
3. Continuous mouse movement: Move the cursor, click, scroll, and drag, all from the keyboard.
4. Hint navigation: Cover the screen with a grid of labeled hints, type a label to jump the cursor there.
5. UI hint navigation: Label buttons, links, and text fields in the active window.
6. 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.
7. Zoom.
8. App-specific behavior: Restrict combos to specific apps, so the same keys behave differently depending on the focused app.
9. Cursor indicator: Custom shape, color, outline, shadow, text label, changes per mouse state.
10. Position history: Save cursor positions, jump back to them later.
11. 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.

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. The remaining work is Linux, for which the overlay is already cross-platform and only input handling is left.
  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!