waywarp

English | 简体中文

A high-performance, keyboard-driven mouse control tool for Wayland compositors (wlroots-based).

Features

• Hint-based cursor positioning: Overlay hint labels on screen, type characters to warp the cursor
• Multi-pass refinement: Coarse grid → fine grid for pixel-perfect accuracy
• Agent CLI mode: JSON output, programmatic hint selection, direct coordinate control
• Callback system: Execute shell commands after positioning (click, type, drag, scroll)
• Multi-monitor support: Auto-detect monitors, per-monitor hint grids

Supported Compositors

• Hyprland
• Sway
• River
• Wayfire
• niri
• Any wlroots-based compositor

Installation

cargo install waywarp

Or build from source:

git clone https://github.com/Xuepoo/waywarp.git
cd waywarp
cargo build --release

Usage

# Interactive hint mode
waywarp

# List hints as JSON
waywarp --list-hints --format json

# Programmatic hint selection
waywarp --select "fa"

# Direct coordinate + click
waywarp --move-to 800 460 --click left

# Relative coordinate move + click (v0.1.2+)
waywarp --move-by 50 -30 --click left

# Start in continuous Normal Mode (cursor drive) (v0.1.3+)
waywarp --normal

Normal Mode Keybindings (Cursor Mode)

When starting with waywarp --normal, you enter a continuous keyboard-driven mouse pointer mode:

Key	Action
h / Left Arrow	Move cursor left
j / Down Arrow	Move cursor down
k / Up Arrow	Move cursor up
l / Right Arrow	Move cursor right
Shift (hold)	3x Speed Boost (Fast acceleration)
Control (hold)	0.25x Speed Divisor (Fine precision)
f / Return	Left Click (Exits if exit_on_select is enabled)
d	Right Click (Exits if exit_on_select is enabled)
s	Middle Click
u	Scroll Up
e	Scroll Down
Escape / q	Exit Normal Mode

Configuration

Waywarp automatically creates a default configuration file at ~/.config/waywarp/config on its first run if it does not exist.

# ~/.config/waywarp/config
on_select_cmd=hyprctl dispatch movecursor {global_x} {global_y}
hint_font=monospace
hint_size=18

For the complete documentation of all configuration options, callbacks, dynamic variables, and integration recipes, refer to the Waywarp Configuration Guide.

License

MIT