Mouse gestures for Linux. Hold a mouse button, draw a stroke, and the window under the cursor gets the action you set for that stroke in that app.
It runs on Hyprland, KDE Plasma 6, GNOME, sway, niri, COSMIC, labwc and X11 desktops, and picks the right one on its own. A quick click of the trigger button is still a click, so middle-click paste keeps working, and holding the button still is still a drag.
Build it with a recent Rust toolchain:
git clone https://github.com/tkutsu/mousewand
cd mousewand
cargo install --path crates/mousewandmousewand reads your mice directly and passes their events on through a virtual mouse. This udev rule lets the logged-in user do that without root:
sudo cp dist/70-mousewand.rules /etc/udev/rules.d/
sudo cp dist/mousewand-uinput.conf /etc/modules-load.d/
sudo modprobe uinput; and sudo udevadm control --reload; and sudo udevadm triggerLog out and back in once. Being in the input group works too.
Run mousewand, hold the middle button and draw. Ctrl+C stops it and gives the mouse back.
To start it with your desktop, add mousewand to your compositor's autostart, such as exec-once in Hyprland, or use the systemd user service:
mkdir -p ~/.config/systemd/user
cp dist/mousewand.service ~/.config/systemd/user/
systemctl --user enable --now mousewandOnly one mousewand runs at a time, so doing both does no harm.
The settings app is optional. It's a Tauri app and needs WebKitGTK (webkit2gtk-4.1), Node and pnpm to build:
pnpm -C crates/mousewand-settings/ui install
pnpm -C crates/mousewand-settings/ui build
cargo install --path crates/mousewand-settingsDraw a circle over a window to open it on that window's app. mousewand-settings --class firefox opens it from a terminal. It edits the same files described below, keeps your comments, and won't save a config mousewand would reject. It can also record a shortcut or detect your trigger button as you press them, offer ready-made actions like Back or Close tab, and teach mousewand new shapes.
~/.config/mousewand/
config.toml settings, gestures for every app, global gestures, hints
apps/<class>.toml gestures for one app, by window class
shapes/<name>.toml shapes drawn in the settings app
themes/<name>.toml trail themes
Changes apply when you save. If a file has an error, mousewand keeps the last working config and shows the error in a notification.
The examples set up Firefox, kitty, volume on the wheel, an alt-tab and hints. Their two workspace gestures use Hyprland dispatchers.
mkdir -p ~/.config/mousewand
cp -r examples/* ~/.config/mousewand/A gesture is an input and an action, with an optional name for hints to show:
# ~/.config/mousewand/apps/firefox.toml
match = ["firefox", "librewolf"]
[[gesture]]
stroke = "L"
name = "Back"
action = { keys = "alt+Left" }Without match, an app file applies to the window class in its file name. An app's gestures replace the ones in config.toml that have the same input.
The input is one of these:
stroke = "DR": directions in the order you draw them.U,D,LandR, and diagonals as numpad digits:7up-left,9up-right,1down-left,3down-right. When nothing matches exactly, the closest stroke fires if it's withinstroke_tolerance: a rounded corner drawn asU9Rcounts asUR. Repeat and hold strokes only match exactly.shape = "circle": a drawn shape. See Shapes.wheel = "up": a wheel notch while you hold the trigger,up,down,leftorright. It fires on every notch.click = "right": aleftorrightclick while you hold the trigger. Withrightas the trigger, onlyleft.
A stroke or shape can also need keys held on the keyboard, so one stroke can do two things. See Modifiers.
The action is one of these:
-
keys = "ctrl+shift+t": a key combo for the window you drew over. Keys are positions on a US keyboard, whatever your layout. -
command = "...": a shell command. It gets$MOUSEWAND_CLASSand$MOUSEWAND_TITLE, and the selected text in$SELECTION. See Using the selected text. -
dispatch = "...": a compositor command. See Desktops for what each one takes.
An action can also be a list of steps, run one after another. Each step waits for the one before it to finish, a command for up to 3 seconds, and wait pauses for that many milliseconds:
[[gesture]]
stroke = "UR"
name = "Duplicate tab"
action = [{ keys = "ctrl+l" }, { wait = 50 }, { keys = "alt+Enter" }]A stroke can keep firing while you hold the trigger. With repeat = true it fires when it's recognized, again for every step pixels (80 by default) you keep moving in its last direction, and on every wheel notch, which suits scrubbing through tabs. With hold in the action it does the same and holds those keys down until you let go, which makes a real alt-tab:
[[gesture]]
stroke = "9"
name = "Switch windows"
action = { keys = "Tab", hold = "alt" }A repeating stroke takes over as soon as it's drawn, so no other stroke may start with it. mousewand rejects a config where one does.
A shape matches by how the drawing looks rather than its directions. A circle counts when it's squashed, tilted, drawn either way round, or not quite closed.
circle, triangle, square, star, heart, check, spiral and infinity are built in. To add a shape, draw it five times in the settings app. It saves the shape as shapes/<name>.toml and lists every shape under Shapes, where you can redraw or remove the ones you drew.
[[gesture]]
shape = "circle"
name = "Reopen tab"
action = { keys = "ctrl+shift+t" }Shapes fire on release and can't repeat or hold keys. A stroke with a gesture of its own takes precedence over a shape. Among shapes, a drawing matches the one it looks most like, but only shapes some gesture uses compete: with just circle in use, a square is round enough to count as a circle.
With with, a stroke or shape only fires while those keys are held on the keyboard, and the same stroke without them can do something else:
[[gesture]]
stroke = "L"
name = "Back"
action = { keys = "alt+Left" }
[[gesture]]
stroke = "L"
with = "shift"
name = "Previous tab"
action = { keys = "ctrl+shift+Tab" }with takes ctrl, shift, alt and super, joined with +, and the keys must match exactly. Only strokes and shapes that fire on release can use it. Their keys are typed once you let go of the modifiers too, so Shift doesn't turn ctrl+t into ctrl+shift+t.
mousewand needs to read the keyboard to know what's held. It only asks which keys are down at the moment a gesture fires, and never reads what you type, but the access it needs would let any program you run read your typing. That's why this udev rule is separate, and only worth installing if you use with:
sudo cp dist/71-mousewand-keyboard.rules /etc/udev/rules.d/
sudo udevadm control --reload; and sudo udevadm triggerBeing in the input group works too.
Gestures are off over games, and over anything else that wants the button for itself. There the trigger is an ordinary button, and so is the [global] trigger. [off] in config.toml lists such windows by class. * matches any run of characters and ? matches one, ignoring case. games, on by default, covers Steam games run through Proton (steam_app_*), anything run through Wine (*.exe) and gamescope. Native Linux games have classes of their own, so list those:
[off]
games = true
match = ["blender", "org.gnome.*"]The General page of the settings app edits the same list. An app file can also turn its app off:
# ~/.config/mousewand/apps/blender.toml
enabled = falsemousewand toggle pauses gestures everywhere, and running it again resumes them. Bind it to a keyboard shortcut in your desktop's settings.
Gestures under [global] are the same in every app, and app files can't replace them. With a trigger of their own, that button runs only them, and the main trigger keeps the app gestures:
[global]
trigger = "back" # optional; without it they share the main trigger
[[global.gesture]]
stroke = "RU"
name = "Next workspace"
action = { dispatch = 'hl.dsp.focus({ workspace = "e+1" })' }On their own button, keys go to the focused window rather than the one under the cursor.
These are the defaults:
trigger = "middle" # middle, right, back (mouse 4), forward (mouse 5), mouse6 to mouse8
threshold = 8 # pixels to move before a press becomes a gesture
hold_ms = 300 # holding still this long makes it a normal press
cancel_ms = 0 # holding still this long mid-stroke cancels it, e.g. 700; 0 never does
min_segment = 30 # shorter strokes are ignored as noise, and so are any under a tenth of the drawing
stroke_tolerance = 30 # degrees a drawing may stray from a stroke and still fire it; 0 only exact
devices = [] # only use mice whose name contains one of these
theme = "default" # a built-in theme, or a file in themes/ without .toml
open_settings = { shape = "circle" } # or a stroke, like { stroke = "U39D" }Hints show the stroke so far as arrows and, in a list beside it, the name of the gesture it matches and what it could still become. A wheel or click gesture shows a mouse with its wheel or button lit, and one that fires again and again, a repeat or the wheel, counts up: "Next tab 3×". Before you draw anything, the list of what you could do includes the wheel and click gestures. Hints fade out with the trail. They're off until you turn them on, under Appearance in the settings app, which also picks a style and shows examples.
[hint]
enabled = true
next = true # list what the stroke could still become
position = "bottom center" # top, center or bottom, with left, center or right
margin = 64 # pixels from the screen edge
font = "sans-serif" # any installed font family
size = 17 # the stroke's size in pixels
next_size = 14 # the list's text size in pixels
text = "#f2f2f7"
next_text = "#8e8e93" # what the stroke could still become"
glyph = "#9ec4ff" # the arrows, mice and counts
failed = "#ff5959" # arrows once the stroke matches nothing
background = "#1c1e26" # "#rrggbbaa" for a see-through background
opacity = 0.9
padding = 14
radius = 14Built in:
- Cool: default, ocean, aurora, mint, matrix
- Warm: ember, fire, sunset, gold
- Soft: sakura, cotton-candy, lavender
- Lines: laser, ink
- Bright: neon, rainbow
- Flags: pride, trans
- Desktop color schemes: catppuccin, dracula, gruvbox, nord, tokyo-night
To make your own, add a file to themes/. A file with a built-in name replaces that theme.
# ~/.config/mousewand/themes/ember.toml
color = "#ff8a3d" # the trail
rejected = "#7f8ca3" # the trail when nothing matched
width = 34 # pixels at the head, glow included
life_ms = 650 # how long the tail lingers
fade_ms = 400 # fade after release
glow = 0.9 # 0 is a plain lineFor a gradient, list colors from head to tail:
color = ["#ffd36e", "#ff8a5c", "#e85d8a", "#7b4bb7"]A command that mentions $SELECTION gets the text you last selected in it, read as the gesture fires. That's the primary selection, which selecting text sets without copying it, from whichever window you selected in. mousewand reads it with wl-paste on Wayland and xclip on X11, so one of them has to be installed.
[[gesture]]
stroke = "UR"
name = "Copy selection"
action = { command = 'printf %s "$SELECTION" | wl-copy' }
[[gesture]]
stroke = "UL"
name = "Search selection"
action = { command = 'xdg-open "https://duckduckgo.com/?q=$(printf %s "$SELECTION" | jq -sRr @uri)"' }| Gestures go to | dispatch runs |
|
|---|---|---|
| Hyprland | the window under the cursor | a dispatcher: 'hl.dsp.focus({ workspace = "e+1" })' with a Lua config, "workspace e+1" before |
| KDE Plasma 6 | the window under the cursor | a KWin shortcut by name, like "Window Maximize" |
| GNOME | the window under the cursor | nothing |
| X11 (Xfce, Cinnamon, MATE, i3 and others) | the window under the cursor | nothing |
| sway | the focused window | a sway command, like "fullscreen toggle" |
| niri | the focused window | a niri action, like "maximize-column" |
| COSMIC, labwc | the focused window | nothing |
sway, niri, COSMIC and labwc don't tell other programs which window is under the cursor, so gestures go to the focused one. With focus-follows-mouse on, that's the same window.
On start, mousewand sets up what it can:
- Hyprland: it turns off the layer animation for its trail in the running session, and again after each config reload.
- GNOME: it installs and enables its Shell extension, which draws the trail. GNOME loads new extensions at login, so log out and back in once.
- niri: it adds
focus-follows-mousetoconfig.kdlonce, afterniri validateaccepts the change, and keeps the old file asconfig.kdl.mousewand-backup. - X11: it starts picom for the trail if no compositing manager is running, and stops it on exit.
It tells you once about anything left to do by hand, like focus-follows-mouse in labwc or COSMIC, in the settings app or in a notification. To pick a backend yourself, set MOUSEWAND_BACKEND to hyprland, sway, niri, kwin, gnome, x11 or toplevel.
The log is in journalctl --user -u mousewand -f, or in the terminal if you run mousewand there. RUST_LOG=mousewand=debug adds the window class each gesture matched and the stroke it saw.
The log should say grabbed and your mouse's name. If it doesn't, or it asks whether /dev/uinput is writable, the udev rule hasn't taken effect yet: log out and back in. With several mice, check that devices in config.toml includes yours.
The log shows what mousewand saw, like DUDU: no gesture, or U9R: close to UR when it fired the closest stroke. Draw more slowly, or lower min_segment.
On sway, niri, COSMIC and labwc, gestures go to the focused window. Turn on focus-follows-mouse.
On GNOME, log out and back in once after the first start. On X11, mousewand needs picom or another compositing manager. Anywhere else, look for no trail: in the log. The trail needs a working GPU driver.
A click stays a click unless you draw a stroke, and holding still for hold_ms makes a normal press, for middle-drag and autoscroll. If quick flicks still turn into strokes, raise min_segment.
The log says can't read the keyboard once if mousewand can't see which keys are held. Install the rule in Modifiers, then log out and back in. A gesture with = "shift" doesn't fire while Ctrl is held too.
With cancel_ms set, holding still that long cancels a stroke, and the hint says "Cancelled". A repeating gesture that has already taken over doesn't cancel.
A stroke with a gesture takes precedence over a shape, and a repeating stroke takes over as soon as it's drawn. Debug logging shows which stroke your circle made.
A repeating gesture took over, and each ring is one repeat. A one-direction repeating stroke, like the example alt-tab on 9, catches every stroke that starts in that direction. Give it a longer stroke.
The compositor now sees one virtual mouse, "mousewand virtual mouse". Apply per-device settings, like an acceleration profile, to it.
keys uses US key positions. On another layout, write the key in the same place on a US keyboard.
Hints are off by default. Turn them on under Appearance in the settings app, or set enabled = true under [hint]. If hints show arrows but no text, the font isn't installed. fc-match "Font Name" shows what it resolves to.
An app file uses the same input as a global gesture that shares the main trigger. Change one of them, or give [global] its own trigger.
The gesture format changed. kind = "repeat" is now repeat = true, hold goes in the action, and rocker is now click.
Stopping mousewand gives it back: systemctl --user stop mousewand, or pkill mousewand.
cargo test runs the unit tests for recognition, the config and the gesture state machine.
The settings app has its own tests, run from its folder. The first time, pnpm exec playwright install chromium fetches the browser they use.
cd crates/mousewand-settings/ui
pnpm test # the TypeScript logic, with Vitest
pnpm test:ui # clicking through the app in Chromium, against a fake backend
pnpm test:look # every page, light and dark, against the shots in e2e/look/After a change meant to alter how a page looks, pnpm test:look --update-snapshots takes new shots.
tools/vm/vm.sh runs mousewand end to end in a throwaway Arch VM on Hyprland, sway, KDE, GNOME, niri, labwc, COSMIC and X11. A fake mouse inside the guest draws over two terminal windows, and the suite checks what each gesture did: per-app gestures, keys, lists of steps, repeating and held keys, the wheel, clicks, shapes, modifiers, pausing, config reloads, click replay, $SELECTION and dispatch. It needs qemu with KVM and 8 GB of free memory.
tools/vm/vm.sh setup # once: download the image
tools/vm/vm.sh start # boot; the first boot installs the desktops
tools/vm/vm.sh test # every desktop, or some: tools/vm/vm.sh test sway kwin
tools/vm/vm.sh stopEach run also takes screenshots of the trail and the hint in the middle of a stroke. Subtracting the shot taken just before the stroke leaves only what mousewand drew, and that must match what it drew on Hyprland: the same place, shape and color, within a tolerance, since GNOME and X11 draw with their own code. ~/.cache/mousewand-vm/report.html shows each desktop's drawing beside Hyprland's. The VM's Hyprland takes its look from settings.lua, decoration.lua and animation.lua in your ~/.config/hypr/configs/, if they're there.
If port 2222 is taken, set MOUSEWAND_VM_PORT to another one.
MIT or Apache-2.0, at your option.
