hypruse [hybrid-use]

Hyprland-native computer-use backend for MCP-capable agents (OpenCode, Claude Code, and anything speaking MCP).

No Xvfb, no X11 hacks. Uses Hyprland's native IPC + wlr virtual pointer protocols for cursor/keyboard injection on actual Wayland sessions.

how it works

Hyprland has no xdotool. Wayland doesn't let clients inject input into other surfaces. But hypruse bridges the gap with:

grim / grimblast for screen capture (wlr-screencopy)
hyprctl dispatch movecursor for absolute cursor positioning (Hyprland's native IPC)
ydotool (uinput) or wlrctl (wlroots virtual-pointer protocol) for click/type/scroll injection
Coordinate math that maps screenshot pixels to compositor-space coordinates (handles multi-monitor)

install

# install deps
sudo pacman -S grim ydotool  # or grimblast from AUR

# start ydotoold daemon
systemctl --user enable --now ydotoold

# install hypruse
pip install .
# or
uv tool install .

backend options

backend	pros	cons
`ydotool` (default)	works on any compositor	needs `ydotoold` daemon + uinput perms
`wlrctl`	no daemon needed	wlroots-only (Hyprland qualifies)

usage

CLI (manual testing)

hypruse screenshot -o test.png
hypruse click 800 450
hypruse move 400 300
hypruse type "hello world"
hypruse key ctrl+s
hypruse monitors
hypruse active
hypruse cursorpos

MCP server (for agents)

hypruse-mcp

Flags: --dry-run, --confirm-destructive, --target-width 1600, --target-height 900, --backend auto

MCP configuration

OpenCode (`~/.config/opencode.json`)

{
  "mcpServers": {
    "hypruse": {
      "command": "hypruse-mcp",
      "args": []
    }
  }
}

Claude Code (`.mcp.json` in project, or `~/.mcp.json`)

{
  "mcpServers": {
    "hypruse": {
      "command": "hypruse-mcp",
      "args": []
    }
  }
}

Or via CLI:

claude mcp add hypruse --cmd hypruse-mcp

available MCP tools

tool	params	what it does
`screenshot`	`region?`, `monitor?`	captures screen, returns PNG + display dims
`zoom`	`region`	crops+scales a region from last screenshot
`move_mouse`	`x`, `y`	moves cursor (screenshot space -> compositor space)
`click`	`x`, `y`, `button?`, `clicks?`, `keys?`	move + click
`mouse_down`	`button?`	press and hold
`mouse_up`	`button?`	release
`drag`	`path`, `button?`, `keys?`	click-drag through points
`scroll`	`x?`, `y?`, `dx`, `dy`	move + scroll
`type_text`	`text`	keyboard type
`key`	`combo`	key combo (both `ctrl+s` and `["CTRL","S"]` work)
`hold_key`	`combo`, `duration_s?`	hold for duration
`wait`	`duration_s?`	sleep
`get_monitors`	-	monitor layout json
`get_active_window`	-	active window info

safety features

deny-list: certain key combos (ctrl+c, alt+f4, etc) trigger confirmation prompts
action log: every call logged to ~/.local/state/hypruse/actions.log
dry-run: --dry-run logs everything but executes nothing

coordinate system

All coordinates are in the last screenshot's pixel space. Internally hypruse translates them to Hyprland's compositor space using hyprctl monitors -j offsets. The scale factor from original resolution to delivered screenshot is handled transparently.

deny list config

~/.config/hypruse/config.json:

{
  "deny_list": ["ctrl+c", "alt+f4", "super+q"],
  "target_width": 1600,
  "target_height": 900,
  "backend": "auto"
}