swaitsandClaude Opus 4.6
e22d8251ed
Keyboard-driven mouse navigation overlay for Wayland using wlr-layer-shell and wlr-virtual-pointer. Two-key grid selection, click/double-click/right-click/drag, three-tier cursor nudge (hjkl/HJKL/Ctrl+hjkl), and scroll passthrough. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
81 lines
2.3 KiB
Markdown
81 lines
2.3 KiB
Markdown
# mousefree
|
||
|
||
Keyboard-driven mouse navigation for Wayland. Launch the overlay, type two keys
|
||
to jump the cursor to a grid cell, then click, drag, or scroll — all without
|
||
touching the mouse.
|
||
|
||
## Requirements
|
||
|
||
- A Wayland compositor with `wlr-layer-shell` and `wlr-virtual-pointer` support
|
||
(Sway, Hyprland, river, etc.)
|
||
- `fontconfig` (`fc-match`) for system font discovery
|
||
- US QWERTY keyboard layout (other layouts are not yet supported)
|
||
|
||
## Install
|
||
|
||
With [mise](https://mise.jdx.dev/):
|
||
|
||
```sh
|
||
mise use -g cargo:mousefree
|
||
```
|
||
|
||
Or with cargo directly:
|
||
|
||
```sh
|
||
cargo install mousefree
|
||
```
|
||
|
||
Or build from source:
|
||
|
||
```sh
|
||
git clone https://github.com/swaits/mousefree.git
|
||
cd mousefree
|
||
cargo install --path .
|
||
```
|
||
|
||
Then bind `mousefree` to a hotkey in your compositor. Every Wayland compositor
|
||
has its own way to bind a key to launch a program — consult your compositor's
|
||
docs. For example, in Sway:
|
||
|
||
```
|
||
bindsym $mod+semicolon exec mousefree
|
||
```
|
||
|
||
### Controls
|
||
|
||
| Key | Action |
|
||
|-----|--------|
|
||
| `a`–`p` | Select column |
|
||
| `q`,`w`,`e`,… | Select row (completes cell selection) |
|
||
| `Space` | Click |
|
||
| `Enter` | Double-click |
|
||
| `Shift`+`Enter` | Triple-click (select line/paragraph) |
|
||
| `.` | Right-click |
|
||
| `/` | Start drag (type a second cell to drop) |
|
||
| `h` `j` `k` `l` | Nudge cursor (8 px) |
|
||
| `H` `J` `K` `L` | Medium nudge (16 px) |
|
||
| `Ctrl`+`h` `j` `k` `l` | Large nudge (32 px) |
|
||
| `Alt`+`h` `j` `k` `l` | Pixel-perfect nudge (1 px) |
|
||
| Arrow keys | Scroll |
|
||
| `Backspace` | Undo / go back |
|
||
| `Escape` | Quit |
|
||
|
||
Keys like `h`, `j`, `k`, `l` are context-sensitive: before a cell is selected
|
||
they choose a column/row; after a cell is locked they nudge the cursor.
|
||
|
||
## Troubleshooting
|
||
|
||
- **"could not find a system font"** — Install fontconfig (`sudo apt install
|
||
fontconfig` / `sudo pacman -S fontconfig`) and verify with `fc-match
|
||
sans-serif`.
|
||
- **Overlay does not appear** — Your compositor may not support
|
||
`wlr-layer-shell` or `wlr-virtual-pointer`. Try Sway, Hyprland, or river.
|
||
- **Keys produce wrong characters** — mousefree currently assumes a US QWERTY
|
||
layout. Other layouts are not yet supported.
|
||
- **Virtual pointer stuck after crash** — If the process is killed mid-drag, a
|
||
mouse button may stay pressed. Restarting your compositor session clears it.
|
||
|
||
## License
|
||
|
||
[MIT](LICENSE)
|