Keymouse

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

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
• Configurable grid labels, theme presets, and opacity (hot-reloads while running)
• 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

Create a macOS app bundle (recommended for Spotlight/Finder launch):

keymouse --install-app

Then launch Keymouse from Spotlight or from ~/Applications/Keymouse.app.

You can still run directly from terminal:

keymouse

Both paths launch Keymouse as a macOS menu bar app (KM).

Option 2: Download a prebuilt binary from GitHub Releases

Latest release:

• https://github.com/debacodes10/keymouse/releases/latest

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.

Launch from:

• Spotlight: type Keymouse
• Finder: ~/Applications/Keymouse.app

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

See all available commands anytime:

keymouse --help

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) Easy access

• Keep using Spotlight (Cmd+Space, then type Keymouse).
• Optional: in Finder, open ~/Applications, right-click Keymouse.app, then choose Add to Dock.
• To auto-start on login, open the menu bar item KM -> Start at Login.

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

5) 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

6) Use jump grid mode

• Press ; (default grid_key) to show the 3x3 grid on the display under the cursor.
• While grid mode is open, press 1..9 to switch to monitor 1..9 (ordered left-to-right, then top-to-bottom).
• 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
1..9 (in grid mode)	Switch active monitor
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"

grid_theme = "classic"
grid_opacity = 1.0
grid_color = "#4fd1ff"
grid_labels = ["Q", "W", "E", "A", "S", "D", "Z", "X", "C"]

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.

Grid overlay visual options:

• grid_theme: classic, midnight, ocean, forest
• grid_opacity: 0.0 to 1.0
• grid_color: optional accent color (#RRGGBB) for grid border/depth tint
• grid_labels: exactly 9 strings (visual labels only)

Keymouse hot-reloads these grid visual options when config.toml changes.

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.