waywarp 0.1.3

A high-performance, keyboard-driven mouse control tool for Wayland compositors
waywarp-0.1.3 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

# 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