keymouse 0.2.1

Control your mouse using Vim-style keyboard navigation
keymouse-0.2.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

  • Move the cursor with H J K L (normal speed)
  • Hold Shift for fast movement, Option/Alt for slow movement
  • Trigger mouse clicks from the keyboard (F for left click, D for right click)
  • Jump the cursor with a recursive 3x3 grid targeting system
  • Translucent on-screen grid overlay with cell labels (Q W E / A S D / Z X C)
  • Live overlay depth indicator while zooming (Depth: 0, Depth: 1, ...)
  • Multi-monitor aware cursor jumping
  • System-level keyboard interception using macOS CGEventTap
  • Built in Rust with low-level event handling

How It Works

  • Press F8 to toggle mouse mode on or off.
  • In mouse mode, use H J K L to move the cursor.
  • Hold Shift while moving for fast steps, or Option/Alt for slow steps.
  • Press F for left click, D for right click.
  • Press ; to open jump grid mode (overlay appears on the active display).
  • Press grid keys (QWE / ASD / ZXC) to zoom recursively into cells.
  • Press Enter to confirm jump to the center of the selected cell.
  • Press Esc to cancel grid mode.

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

Start the tool:

keymouse

If you built from source, run:

./target/release/keymouse

Grant macOS permissions to the app launching Keymouse (usually your terminal):

  • System Settings -> Privacy & Security -> Accessibility
  • System Settings -> Privacy & Security -> Input Monitoring
Key Action
F8 Toggle mouse mode
H J K L Move cursor (normal speed)
Shift + H/J/K/L Move cursor fast
Option + H/J/K/L Move cursor slow
F Left click
D Right click
; Open jump grid overlay on active display
Q/W/E/A/S/D/Z/X/C Select grid cell and keep zooming in
Enter Confirm grid selection and move cursor to selected cell center
Esc Cancel grid mode

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"

grid_key = ";"
confirm_key = "enter"

left_click = "f"
right_click = "d"

fast_modifier = "shift"
slow_modifier = "option"

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

This repository does not currently include a license file.