mousefree/README.md

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:

mise use -g cargo:mousefree

Or with cargo directly:

cargo install mousefree

Or build from source:

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