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

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