keymouse 0.5.1

Control your mouse using Vim-style keyboard navigation
keymouse-0.5.1 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
  • 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:

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

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.