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)

Related MCP server: mcp-screenshot

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

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

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"
}