keymouse 0.3.2

Control your mouse using Vim-style keyboard navigation
keymouse-0.3.2 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)
  • Toggleable mouse mode (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)
  • 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

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

If you built from source:

./target/release/keymouse

Validate your config without starting the event loop:

keymouse --check-config

2) Grant macOS permissions

Grant permissions to the app that launches Keymouse (usually Terminal/iTerm):

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

3) Toggle mouse mode

  • Press F8 to 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) Control the pointer

  • Move: H J K L
  • Scroll: U N B M
  • Click: F (left), D (right)
  • 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
; 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.

Configuration

Keymouse loads configuration from:

~/.config/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:

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"

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 w x z)
  • ; (or "semicolon"), "enter"/"return", "escape"/"esc", "f8"
  • Modifiers: "shift" and "option"/"alt" (for modifier fields)

Unknown key names fall back to default values.

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.

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.