gitwtfhub

wtf is hypruse?

ilyaskhallouki/hypruse — explained in plain English

Analysis updated 2026-05-18

6PythonAudience · developerComplexity · 4/5Setup · moderate

TL;DR

Hypruse is an MCP server that gives AI agents real control over a Hyprland Wayland desktop: window management, screenshots, mouse, and keyboard, without root or portals.

Mindmap

mindmap
  root((hypruse))
    What it does
      Controls Hyprland desktop
      Semantic window state
      Screenshots and zoom
      Mouse and keyboard input
    Tech stack
      Python
      MCP
      Hyprland
      Wayland
    Use cases
      AI computer use on Linux
      Desktop automation
      GUI testing agents
    Audience
      Developers
      AI agent builders

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

Why would anyone build with this?

REASON 1

Let an AI agent inspect and control a Hyprland Wayland desktop for automated GUI tasks.

REASON 2

Have an agent read window state and click named controls without relying only on screenshots.

REASON 3

Automate multi-step desktop workflows like launching apps and waiting for window events.

What's in the stack?

PythonMCPHyprlandWayland

How it stacks up

ilyaskhallouki/hypruseaclark4life/home-depot-crawlaetheria-labs1/storefront-skills
Stars666
LanguagePythonPythonPython
Last pushed2014-08-10
MaintenanceDormant
Setup difficultymoderatemoderateeasy
Complexity4/52/53/5
Audiencedeveloperdeveloperpm founder

Figures from each repo's GitHub metadata at analysis time.

How do you spin it up?

Difficulty · moderate Time to first run · 1h+

Requires a Hyprland/Wayland Linux desktop, some tools need optional ImageMagick or wl-clipboard installed.

No license information is stated in the README.

Wtf does this do

Hypruse gives an AI agent the ability to actually control a Linux desktop that runs Hyprland, a window manager for the Wayland display system. In plain terms, it lets an AI see your workspaces and open windows, take screenshots, move the mouse, click things, and type text, similar to what companies like Anthropic and Microsoft offer for macOS and Windows through their own computer use features. On Linux, and specifically on Wayland based setups, this kind of capability has been mostly missing, and the few existing attempts often rely on workarounds requiring root access or special permissions. Hypruse works differently by connecting directly to features Hyprland already provides. It follows what the README calls a semantic first approach: instead of only taking screenshots and guessing where things are on screen, it can ask the desktop directly for a structured list of open windows, their titles, and their positions, the same way switching windows normally works, just done programmatically and instantly. When visual information is genuinely needed, it can take screenshots of a whole monitor, a specific window, or a zoomed in region. For actually interacting with the desktop, mouse clicks and scrolling are sent through Wayland's own input system, and typing goes through a tool called wtype that supports proper keyboard layouts and special characters. The project exposes a defined list of tools an agent can call, including getting the desktop state, taking screenshots, reading accessible on screen controls by name, clicking those controls directly, running keyboard shortcuts, launching applications, and waiting for specific desktop events like a window opening or closing. Under the hood, this is an MCP server, meaning it is designed to plug into AI agent systems like Claude Code that support the Model Context Protocol standard. Some advanced features depend on optional external programs being installed, such as ImageMagick for drawing numbered overlays on screenshots. The project's own documentation includes a written explanation of its architecture and a document specifically addressing potential security concerns of giving an agent this level of control.

Yoink these prompts

Prompt 1
Set up hypruse as an MCP server so Claude Code can control my Hyprland desktop.
Prompt 2
Explain how hypruse's semantic desktop state differs from a screenshot-based computer use approach.
Prompt 3
Show me how to use the click_ui tool to click a named control without a screenshot.
Prompt 4
Walk me through installing the optional ImageMagick and wl-clipboard dependencies for hypruse.

Frequently asked questions

wtf is hypruse?

Hypruse is an MCP server that gives AI agents real control over a Hyprland Wayland desktop: window management, screenshots, mouse, and keyboard, without root or portals.

What language is hypruse written in?

Mainly Python. The stack also includes Python, MCP, Hyprland.

What license does hypruse use?

No license information is stated in the README.

How hard is hypruse to set up?

Setup difficulty is rated moderate, with roughly 1h+ to a first successful run.

Who is hypruse for?

Mainly developer.

View the repo → Decode another repo

This repo across BitVibe Labs

Don't trust strangers blindly. Verify against the repo.