waywarp 0.1.2

A high-performance, keyboard-driven mouse control tool for Wayland compositors
waywarp-0.1.2 is not a library.

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

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