# 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)
```bash
cargo install keymouse
```
Create a macOS app bundle (recommended for Spotlight/Finder launch):
```bash
keymouse --install-app
```
Then launch `Keymouse` from Spotlight or from `~/Applications/Keymouse.app`.
You can still run directly from terminal:
```bash
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):
```bash
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:
```bash
git clone https://github.com/debacodes10/keymouse.git
cd keymouse
```
Build a release binary:
```bash
cargo build --release
```
The compiled binary will be available at:
```bash
target/release/keymouse
```
### Windows build-permission workaround
Windows App Control or Smart App Control can block Cargo from executing build scripts when a repo lives under `Downloads`. Keymouse does not hardcode a machine-specific Cargo target path anymore; instead, use the included wrapper or set an override explicitly.
PowerShell:
```powershell
.\scripts\cargo-safe.ps1 run
.\scripts\cargo-safe.ps1 build --release
```
macOS / bash:
```bash
./scripts/cargo-safe.sh run
./scripts/cargo-safe.sh build --release
```
Optional explicit override for a trusted executable directory:
```powershell
$env:KEYMOUSE_CARGO_TARGET_DIR="$env:LOCALAPPDATA\\keymouse\\cargo-target"
.\scripts\cargo-safe.ps1 run
```
```bash
export KEYMOUSE_CARGO_TARGET_DIR="$HOME/.keymouse/cargo-target"
./scripts/cargo-safe.sh run
```
On Windows, `cargo-safe.ps1` automatically switches builds under `Downloads` to `%LOCALAPPDATA%\keymouse\cargo-target` unless you set `KEYMOUSE_CARGO_TARGET_DIR` yourself. On macOS, normal `cargo run` and `cargo build` continue to use Cargo defaults unless you opt into an override.
## Usage
### 1) Start Keymouse
```bash
keymouse
```
Install a Spotlight-launchable app bundle after `cargo install`:
```bash
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:
```bash
keymouse --uninstall-app
```
Keymouse asks for confirmation before uninstalling.
Run as a managed background process:
```bash
keymouse --start
```
If you built from source:
```bash
./target/release/keymouse
```
Validate your config without starting the event loop:
```bash
keymouse --check-config
```
See all available commands anytime:
```bash
keymouse --help
```
Run without menu bar UI (legacy headless mode):
```bash
keymouse --headless
```
Stop the managed background process:
```bash
keymouse --stop
```
Restart the managed background process:
```bash
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
| `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:
```bash
keymouse --stop
```
## Configuration
Keymouse loads configuration from:
```text
~/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`:
```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
- [x] Vim-style cursor movement
- [x] Grid jump navigation
- [x] Multi-monitor support
- [x] Recursive grid zoom
- [x] Custom key bindings
- [x] 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`](LICENSE).
