keymouse 0.4.5

Control your mouse using Vim-style keyboard navigation
keymouse-0.4.5 is not a library.

Keymouse

Control your mouse on macOS with fast, Vim-style keyboard navigation.

Keymouse Demo

Demo: toggling mouse mode, moving with H J K L, clicking, and jumping the cursor with the grid system.

Features

  • Global keyboard-driven mouse control on macOS (CGEventTap)
  • Menu bar app mode (no dedicated terminal required)
  • Start-at-login toggle from menu bar (LaunchAgent)
  • Toggleable mouse mode (configurable toggle_key, default: F8) so normal typing is unaffected when off
  • Cursor movement with configurable keys (defaults: H J K L)
  • Speed modifiers for movement/scroll (defaults: Shift fast, Option/Alt slow)
  • Scroll control with configurable keys (defaults: U N B M)
  • Left/right click from keyboard (defaults: F / D)
  • Drag toggle to hold/release left mouse button (default: V)
  • Recursive 3x3 jump grid with translucent overlay and depth indicator
  • Multi-monitor aware grid targeting on the display under the cursor
  • Automatic event-tap re-enable if macOS temporarily disables the tap

Installation

Option 1: Install from crates.io (recommended)

cargo install keymouse

Run it:

keymouse

This launches Keymouse as a macOS menu bar app (KM).

Option 2: Download a prebuilt binary from GitHub Releases

Latest release:

Example (Apple Silicon / arm64):

curl -L -o keymouse-macos-arm64.zip https://github.com/debacodes10/keymouse/releases/latest/download/keymouse-macos-arm64.zip
unzip keymouse-macos-arm64.zip
chmod +x keymouse-macos-arm64
./keymouse-macos-arm64

Option 3: Build from source

Clone the repository:

git clone https://github.com/debacodes10/keymouse.git
cd keymouse

Build a release binary:

cargo build --release

The compiled binary will be available at:

target/release/keymouse

Usage

1) Start Keymouse

keymouse

Install a Spotlight-launchable app bundle after cargo install:

keymouse --install-app

If an existing app bundle is found, Keymouse asks before replacing it.

Remove the app bundle:

keymouse --uninstall-app

Keymouse asks for confirmation before uninstalling.

Run as a managed background process:

keymouse --start

If you built from source:

./target/release/keymouse

Validate your config without starting the event loop:

keymouse --check-config

Run without menu bar UI (legacy headless mode):

keymouse --headless

Stop the managed background process:

keymouse --stop

Restart the managed background process:

keymouse --restart

2) Grant macOS permissions

Grant permissions to the app that launches Keymouse:

  • System Settings -> Privacy & Security -> Accessibility
  • System Settings -> Privacy & Security -> Input Monitoring

If launching from Spotlight, this is usually Keymouse.app. If launching from terminal, this is usually Terminal/iTerm.

3) Toggle mouse mode

  • Press your configured toggle_key to turn mouse mode on/off (default: F8).
  • Or use the menu bar item: KM -> Turn Mouse Mode On/Off.
  • When mouse mode is off, all keys behave normally.
  • When mouse mode is on, keydown/keyup events are intercepted by Keymouse.

4) Start at login

  • In the menu bar app, use KM -> Start at Login.
  • This installs/removes a user LaunchAgent for the current executable path.

4) Control the pointer

  • Move: H J K L (hold keys for continuous movement)
  • Scroll: U N B M
  • Click: F (left), D (right)
  • Drag: V to hold left mouse button, V again to release
  • Modifiers: Shift = fast, Option/Alt = slow

5) Use jump grid mode

  • Press ; (default grid_key) to show the 3x3 grid on the display under the cursor.
  • Select cells with Q/W/E, A/S/D, Z/X/C to zoom recursively.
  • Optional alternates in grid mode: F maps to middle-left, G maps to center.
  • Press Enter to move cursor to the selected region center.
  • Press Esc to cancel grid mode.

Default keymap

Key Action
F8 Toggle mouse mode
H J K L Move cursor
Shift + move/scroll keys Fast movement/scroll
Option + move/scroll keys Slow movement/scroll
U N B M Scroll up/down/left/right
F Left click
D Right click
V Toggle drag (left button hold/release)
; Enter grid mode
Q/W/E/A/S/D/Z/X/C Select grid cell recursively
Enter Confirm grid jump
Esc Cancel grid mode

Quit

Use Ctrl+C in the terminal running Keymouse.

If started with --start, stop it with:

keymouse --stop

Configuration

Keymouse loads configuration from:

~/Library/Application Support/keymouse/config.toml

If the file is missing, Keymouse uses built-in defaults. At startup, it also writes an example file to that path so you can customize bindings.

Example config.toml:

toggle_key = "f1"

movement_up = "k"
movement_down = "j"
movement_left = "h"
movement_right = "l"

scroll_up = "u"
scroll_down = "n"
scroll_left = "b"
scroll_right = "m"

grid_key = ";"
confirm_key = "enter"

left_click = "f"
right_click = "d"
drag_toggle = "v"

fast_modifier = "shift"
slow_modifier = "option"

Supported key names for bindings are currently:

  • Letters used by default (a b c d e f g h j k l m n q s u v w x z)
  • ; (or "semicolon"), "enter"/"return", "escape"/"esc", function keys ("f1" ... "f12")
  • Modifiers: "shift" and "option"/"alt" (for modifier fields)

Invalid or conflicting config values now produce startup validation errors.

Troubleshooting

  • If Keymouse exits with an event tap error, re-check Accessibility and Input Monitoring permissions for the launching app.
  • If keyboard control stops after long inactivity or heavy system load, macOS may have disabled the tap; Keymouse now attempts to re-enable it automatically.
  • If Keymouse.app asks for Rosetta on Apple Silicon, reinstall Keymouse from a native (non-Rosetta) terminal, then rerun keymouse --install-app.

Roadmap

  • Vim-style cursor movement
  • Grid jump navigation
  • Multi-monitor support
  • Recursive grid zoom
  • Custom key bindings
  • Configuration file
  • Homebrew installation

Contributing

Contributions, suggestions, and feature requests are welcome. Open an issue to discuss ideas, or submit a pull request with a focused change.

License

MIT. See LICENSE.