SkillFoxx

hypruse MCP

An MCP server and skill giving an agent a Hyprland desktop: window tree, screenshots, named clicks, mouse and keyboard.

  • 60 ★ on the repository
  • Last commit
  • MIT
MCP server

Broad access

Why this level

  • The agent gets your mouse, keyboard, screen contents and app launching on your desktop.
All reasons and checks

ilyaskhallouki/hypruseAuthor:IlyasKhallouki

Install

In your terminal, with SkillFoxx CLI

npx skillfoxx add mcp/hypruse

Detects the agents on your machine, shows the access level and pins the version.

Other ways to install

Access and checks

How we review

Broad accessThe tool can change data, run commands or handle secrets.

  • The agent gets your mouse, keyboard, screen contents and app launching on your desktop.

This is third-party code. Review the repository files before installing.

What it does

hypruse connects an agent to a Hyprland desktop with no compositor plugin, root, portals or X11. The `desktop` tool returns the tree of monitors, workspaces and windows in one call, while `screenshot` and `zoom` capture the screen or a single window. `ui` and `click_ui` read apps' accessibility trees and press controls by name, and `pointer` and `keyboard` drive the mouse and keyboard. In background mode the agent works in apps on its own workspace without moving your cursor or taking focus while you keep working. Install with `yay -S hypruse` or `uv tool install hypruse`, then `hypruse init` registers the server in Claude Code, Codex or Claude Desktop and runs a check.

Who it is for. Linux users on Hyprland or Omarchy who want an agent to work in graphical apps while they keep working themselves.

Good fit when

  • An agent must change a setting in an app that has no command line, such as turning on Do Not Disturb or changing a status.
  • You need a list of windows per workspace without screenshots: `desktop` is enough.
  • An app exposes an accessibility tree and a click by name beats coordinates.
  • The agent must act in the background while you type on your first workspace.

Not a fit when

  • Your environment is not Hyprland: the tool is built for it.
  • You are not ready to hand an agent your keyboard, mouse and screen contents.
  • The task is simpler through a command or API without a graphical interface.

Example request

Use hypruse to list the windows on each of my workspaces.

MCP

Transport
stdio
Authentication
not required

Limitations

It works on Hyprland and on Omarchy. The seat is shared: one cursor and one keyboard focus, and with Hyprland focus-follows-mouse a cursor move alone can retarget keystrokes, so do not type while an agent drives your window. Background mode does not guarantee an app will not bring its own window forward. Element access depends on apps: some expose an empty accessibility tree, leaving screenshots. Read the Security model section first and keep `pointer`, `keyboard`, `hypr` and `launch` on ask-first.

How to disable. Remove the `hypruse` entry from your client configuration, then run `uv tool uninstall hypruse` or remove the package with your distro manager. For an emergency stop bind a key to `hypruse stop`.

FAQ

How do I install it?

Run `yay -S hypruse` or `uv tool install hypruse`, then `hypruse init`: it registers the server in Claude Code, Codex or Claude Desktop after asking and runs a check.

Which tools should I allow first?

Read-only ones: `desktop` and `screenshot`. Keep `pointer`, `keyboard`, `hypr` and `launch` on ask-first until you trust a workflow.

How do I stop the agent?

Click the `Waybar` indicator or bind a hotkey: `bind = SUPER SHIFT, BackSpace, exec, hypruse stop`. Stopping at any moment is safe and held mouse buttons are released.

Does the server open a network port?

No. It runs over stdio only and has no network listener.

Does it work in the background while I am busy?

Yes. In automatic mode, actions on windows outside your focus run in the background and your cursor, focus and workspace stay yours.

Discussion

No questions or reviews yet.

MCP servers

Your own server gives every agent shared memory, AST-level code search and pre-commit checks through one MCP endpoint.

MCP serverBroad access106

A pixel-art office in the browser: each Claude Code or Codex session sits at a desk, types and raises a hand when it needs you.

PluginExtended access60

A local control panel for coding agents: it runs Claude Code and Codex, keeps a task queue and merges verified work into main.

CLIBroad access120

A read-only MCP server for the HeyClaude registry: an agent finds skills, MCP servers and hooks and gets ready install commands

MCP serverExtended access309

MCP server for a shared agent room: decisions, tasks verified by another agent and a final report, joined by code.

MCP serverExtended access107

README in short

The repository ships a Python MCP server, shell commands, an agent skill and a `Waybar` module. There is a Hermes integration and packages for Arch and NixOS.

README badge

Original SKILL.md

---
name: hypruse
description: >
  Sees and drives the live Hyprland (Wayland) desktop through the hypruse CLI:
  lists windows and workspaces, focuses, moves, closes and launches apps over
  IPC, takes screenshots and zooms, reads GTK/Qt controls by name from the
  accessibility tree and clicks them, types text, presses shortcuts, runs the
  owner's keybinds, waits for compositor events, reads the clipboard. Use it
  whenever a task needs to look at the screen, operate a GUI application, or
  manage windows or workspaces on Hyprland (including Omarchy): "open X",
  "click the Y button", "what is on my screen", "switch to workspace 3",
  "type this into Z", "screenshot that window", "fill in this form", "close
  the terminal". Not for editing Hyprland or Omarchy config files (use the
  omarchy skill), and not for web pages when a browser tool is available.
license: MIT
compatibility: Linux with a running Hyprland session and the hypruse CLI on PATH (AUR hypruse, uv tool install hypruse, or pipx install hypruse). Needs grim and wtype; ui, marks and click_ui need an AT-SPI bus; marks needs imagemagick.
allowed-tools: Bash(hypruse doctor:*) Bash(hypruse desktop:*) Bash(hypruse screenshot:*) Bash(hypruse zoom:*) Bash(hypruse ui:*) Bash(hypruse marks:*) Bash(hypruse binds:*) Bash(hypruse wait_for:*) Bash(hypruse wait-for:*) Bash(hypruse --help) Read
metadata:
  author: IlyasKhallouki
  version: "0.15.0"
  homepage: https://github.com/IlyasKhallouki/hypruse
---

# hypruse: hands on the Hyprland desktop

Every verb is `hypruse <verb> [args]`. `hypruse --help` lists every verb and
`hypruse <verb> [<action>] --help` is the ground truth for its flags; read it
before guessing. Observation verbs print one plain line per fact; acting verbs print
one result line and exit 0 only when the action was delivered. The same
fifteen tools exist as an MCP server (`claude mcp add -s user hypruse -- uvx
hypruse`); this CLI is for agents that run shell commands.

## Before anything

```bash
hypruse doctor    # exit 0: session, event socket, pointer and grim are green
hypruse desktop   # monitors, workspaces, windows (address, class, title, at, size), active, cursor, layers
```

Read `desktop` first, every task, and act on window addresses. Never take a

Report a problem