Skip to content
Back to search

hypr-computer

MarketplaceWorks with Claude CodeGitHub

Computer use for Hyprland on Linux.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/malik-na--hypr-computer/badge.svg)](/listings/malik-na--hypr-computer)

HTML

<a href="/listings/malik-na--hypr-computer"><img src="/api/listings/malik-na--hypr-computer/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

Run this one command on the Linux machine:

curl -fsSL malik-na.github.io/hypr-computer | bash

It shows what it will do and asks before starting. Then it:

1. Downloads this repo to `~/.local/share/hypr-computer`. 2. Uses `sudo` once to install `grim`, `wtype`, `ydotool` (and `uv` if it's missing), let your user use `/dev/uinput`, load `uinput` at boot and enable the `ydotool` user service. 3. Runs a read-only self-check. 4. Registers the server with each supported agent you've used (it checks for the agent's config folder): Claude Code, Codex, opencode, Gemini CLI and Cursor.

Then restart your agent. To update later, run the same command again.

Options go after `bash -s --`, for example `curl -fsSL malik-na.github.io/hypr-computer | bash -s -- --clients=claude --yes`:

| Option | Effect | | --- | --- | | `--yes` | Don't ask for confirmation | | `--dry-run` | Show every step and change nothing | | `--clients=claude,codex` | Only register these agents (`none` to skip) | | `--no-system` | Skip the sudo step (already done, or not on Arch) | | `--dir=PATH` | Install somewhere other than `~/.local/share/hypr-computer` |

Automatic system setup needs a pacman-based distro (Arch, Arch Linux ARM, Omarchy). On other distros, install `grim`, `wtype`, `ydotool` and `uv`, apply [`scripts/install-system.sh`](scripts/install-system.sh) by hand, and run the installer with `--no-system`.

Claude Code users can also install this as a plugin instead: `claude plugin marketplace add malik-na/hypr-computer && claude plugin install hypr-computer@hypr-computer`.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 12 lines
  1. {
  2. "name": "hypr-computer",
  3. "owner": { "name": "Naeem Malik" },
  4. "description": "Computer use for Hyprland on Linux.",
  5. "plugins": [
  6. {
  7. "name": "hypr-computer",
  8. "source": "./",
  9. "description": "Computer use for Hyprland on Linux: screenshots, clicks, typing and shortcuts through an MCP server."
  10. }
  11. ]
  12. }
README.md · README · 373 lines · 3 findings marked
  1. # hypr-computer
  2. Computer use for any MCP-capable AI agent on Linux with Hyprland. It's a single
  3. stdio MCP server that lets the model see the screen (screenshots) and drive the
  4. mouse and keyboard. It works with Claude Code, Codex, Gemini CLI, Cursor,
  5. VS Code, opencode and any other client that supports local MCP servers.
  6. It was built and tested on a 16-inch MacBook Pro with an M3 Max, running Omarchy 4.5
  7. and Hyprland 0.56 on Arch Linux ARM with the `linux-aurora` 7.2.11 kernel.
  8. ## Install
  9. Run this one command on the Linux machine:
  10. ```bash
  11. curl -fsSL malik-na.github.io/hypr-computer | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 16 on GitHub
  12. ```
  13. It shows what it will do and asks before starting. Then it:
  14. 1. Downloads this repo to `~/.local/share/hypr-computer`.
  15. 2. Uses `sudo` once to install `grim`, `wtype`, `ydotool` (and `uv` if it's
  16. missing), let your user use `/dev/uinput`, load `uinput` at boot and enable
  17. the `ydotool` user service.
  18. 3. Runs a read-only self-check.
  19. 4. Registers the server with each supported agent you've used (it checks for the
  20. agent's config folder): Claude Code, Codex, opencode, Gemini CLI and Cursor.
  21. Then restart your agent. To update later, run the same command again.
  22. Options go after `bash -s --`, for example
  23. `curl -fsSL malik-na.github.io/hypr-computer | bash -s -- --clients=claude --yes`:
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 32 on GitHub
  24. | Option | Effect |
  25. | --- | --- |
  26. | `--yes` | Don't ask for confirmation |
  27. | `--dry-run` | Show every step and change nothing |
  28. | `--clients=claude,codex` | Only register these agents (`none` to skip) |
  29. | `--no-system` | Skip the sudo step (already done, or not on Arch) |
  30. | `--dir=PATH` | Install somewhere other than `~/.local/share/hypr-computer` |
  31. Automatic system setup needs a pacman-based distro (Arch, Arch Linux ARM,
  32. Omarchy). On other distros, install `grim`, `wtype`, `ydotool` and `uv`, apply
  33. [`scripts/install-system.sh`](scripts/install-system.sh) by hand, and run the
  34. installer with `--no-system`.
  35. Claude Code users can also install this as a plugin instead:
  36. `claude plugin marketplace add malik-na/hypr-computer && claude plugin install hypr-computer@hypr-computer`.
  37. ---
  38. ## For AI agents: setup instructions
  39. You are probably an agent asked to set up computer use on this machine.
  40. 1. **Check support.** Run `hyprctl version | head -1`. You need **Hyprland 0.55 or
  41. newer**. If `hyprctl` is missing or older, stop and tell the user: other
  42. compositors aren't supported. A `tty` or empty `$XDG_SESSION_TYPE` (for example
  43. over SSH) is fine.
  44. 2. **Ask the user first.** Tell them the installer will use `sudo` to install
  45. packages and allow access to `/dev/uinput`, and wait for their OK.
  46. 3. **Install.** Replace `<client>` with the agent you are running in: `claude`,
  47. `codex`, `opencode`, `gemini` or `cursor`. Leave out `--clients` to register
  48. every agent whose config folder exists.
  49. ```bash
  50. curl -fsSL malik-na.github.io/hypr-computer | bash -s -- --yes --clients=<client>
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 66 on GitHub
  51. ```
  52. If `sudo` can't prompt from your environment, ask the user to run the command
  53. themselves in a terminal.
  54. 4. **Read the output.** The self-check prints one `PASS`/`FAIL` line per check
  55. and ends with `hypr-computer is ready.` A failure stops the installer, and
  56. each `FAIL` line names its fix. If `/dev/uinput writable` fails right after a
  57. first install, the user needs to log out and back in, then re-run the command.
  58. 5. **Other clients.** For VS Code, Zed, Goose, Cline or Windsurf, the installer
  59. can't register the server. Add the matching snippet from
  60. [Client configuration](#client-configuration), using the absolute path
  61. `/home/<user>/.local/share/hypr-computer/server.py`.
  62. 6. **Restart, then smoke test.** Ask the user to restart the agent. Then call
  63. `list_windows` and `screenshot`. If you can see the screenshot, setup is
  64. complete. Don't click or type during the test unless the user asks.
  65. To re-check at any time without changing anything:
  66. `uv run --quiet --script ~/.local/share/hypr-computer/server.py --check`
  67. ---
  68. ## Tools
  69. | Tool | What it does |
  70. | --- | --- |
  71. | `screenshot` | Captures every monitor as one JPEG, scaled so its long edge is at most 1456 px |
  72. | `click` | Clicks at `(x, y)`: `left`, `right` or `middle`; `count=2` double-clicks |
  73. | `move` | Moves the pointer, for example to hover |
  74. | `drag` | Drags with the left button from one point to another |
  75. | `scroll` | Scrolls `up`/`down`/`left`/`right` with the wheel at a point |
  76. | `type_text` | Types text into the focused window, including non-ASCII characters |
  77. | `key` | Presses a key or shortcut: `Return`, `ctrl+l`, `super+Return`, `F5` |
  78. | `cursor_position` | Returns the pointer position |
  79. | `list_windows` | Lists windows with workspace, class, title and bounding box |
  80. **All coordinates are pixels in the most recent screenshot.** Take a new
  81. screenshot after anything that changes the screen, then work out coordinates
  82. from it.
  83. ## Client requirements
  84. - **Image support.** `screenshot` returns MCP `image` content. Both the client
  85. and the model must accept images in tool results. Without that, the model
  86. can't see the screen, and clicking blind doesn't work.
  87. - **Screenshot size.** The default long edge of 1456 px is below the size where
  88. Claude shrinks images, so click coordinates stay accurate. If your model
  89. shrinks images at a smaller size, set `HYPR_COMPUTER_MAX_EDGE` in the server's
  90. environment (for example `1024`). Coordinates follow that size automatically.
  91. ## Client configuration
  92. Replace `/home/USER` with the real home directory in every snippet below. The
  93. formats were checked against each client's official docs in November 2026.
  94. "Images" says whether the client's docs say it passes the `screenshot` image to
  95. the model. "Not documented" means: try `screenshot` once and ask the model
  96. whether it can see the screen.
  97. | Client | Images | Docs |
  98. | --- | --- | --- |
  99. | Claude Code | Yes | [docs](https://code.claude.com/docs/en/mcp) |
  100. | Gemini CLI | Yes | [docs](https://geminicli.com/docs/tools/mcp-server/) |
  101. | Cursor | Yes | [docs](https://cursor.com/docs/context/mcp) |
  102. | Codex CLI | Not documented | [docs](https://learn.chatgpt.com/docs/extend/mcp?surface=cli) |
  103. | VS Code (Copilot) | Not documented | [docs](https://code.visualstudio.com/docs/agents/reference/mcp-configuration) |
  104. | opencode | Not documented (reported unreliable) | [docs](https://opencode.ai/docs/mcp-servers/) |
  105. | Zed | Not documented | [docs](https://zed.dev/docs/ai/mcp) |
  106. | Goose | Not documented | [docs](https://goose-docs.ai/docs/getting-started/using-extensions) |
  107. | Cline | Not documented | [docs](https://docs.cline.bot/mcp/configuring-mcp-servers) |
  108. | Windsurf | Not documented | [docs](https://docs.devin.ai/windsurf/plugins/cascade/mcp.md) |
  109. ### Claude Code
  110. As a plugin (installs from this repo, no clone needed for the server itself):
  111. ```bash
  112. claude plugin marketplace add malik-na/hypr-computer
  113. claude plugin install hypr-computer@hypr-computer
  114. ```
  115. Or as a plain MCP server, using the clone from step 2:
  116. ```bash
  117. claude mcp add --transport stdio --scope user hypr-computer -- uv run --quiet --script /home/USER/.local/share/hypr-computer/server.py
  118. ```
  119. Use only one of the two, or the tools show up twice.
  120. ### Codex CLI
  121. ```bash
  122. codex mcp add hypr-computer -- uv run --quiet --script /home/USER/.local/share/hypr-computer/server.py
  123. ```
  124. Or in `~/.codex/config.toml`:
  125. ```toml
  126. [mcp_servers.hypr-computer]
  127. command = "uv"
  128. args = ["run", "--quiet", "--script", "/home/USER/.local/share/hypr-computer/server.py"]
  129. ```
  130. ### Gemini CLI
  131. In `~/.gemini/settings.json`, merged into any existing `mcpServers`. Prefer the
  132. file to `gemini mcp add`, which may read `--quiet` and `--script` as its own
  133. flags.
  134. ```json
  135. {
  136. "mcpServers": {
  137. "hypr-computer": {
  138. "command": "uv",
  139. "args": ["run", "--quiet", "--script", "/home/USER/.local/share/hypr-computer/server.py"]
  140. }
  141. }
  142. }
  143. ```
  144. ### Cursor
  145. In `~/.cursor/mcp.json`:
  146. ```json
  147. {
  148. "mcpServers": {
  149. "hypr-computer": {
  150. "type": "stdio",
  151. "command": "uv",
  152. "args": ["run", "--quiet", "--script", "/home/USER/.local/share/hypr-computer/server.py"]
  153. }
  154. }
  155. }
  156. ```
  157. ### VS Code (GitHub Copilot agent mode)
  158. In `~/.copilot/mcp-config.json` (or `$COPILOT_HOME/mcp-config.json`):
  159. ```json
  160. {
  161. "mcpServers": {
  162. "hypr-computer": {
  163. "type": "stdio",
  164. "command": "uv",
  165. "args": ["run", "--quiet", "--script", "/home/USER/.local/share/hypr-computer/server.py"],
  166. "tools": ["*"]
  167. }
  168. }
  169. }
  170. ```
  171. The older per-profile setup still works:
  172. `code --add-mcp '{"name":"hypr-computer","type":"stdio","command":"uv","args":["run","--quiet","--script","/home/USER/.local/share/hypr-computer/server.py"]}'`
  173. ### opencode
  174. ```bash
  175. opencode mcp add hypr-computer --global -- uv run --quiet --script /home/USER/.local/share/hypr-computer/server.py
  176. ```
  177. Or in `~/.config/opencode/opencode.json` (arguments go in the `command` array):
  178. ```json
  179. {
  180. "$schema": "https://opencode.ai/config.json",
  181. "mcp": {
  182. "servers": {
  183. "hypr-computer": {
  184. "type": "local",
  185. "command": ["uv", "run", "--quiet", "--script", "/home/USER/.local/share/hypr-computer/server.py"]
  186. }
  187. }
  188. }
  189. }
  190. ```
  191. ### Zed
  192. In Zed's settings file (open it with `zed: open settings file`):
  193. ```json
  194. {
  195. "context_servers": {
  196. "hypr-computer": {
  197. "command": "uv",
  198. "args": ["run", "--quiet", "--script", "/home/USER/.local/share/hypr-computer/server.py"],
  199. "env": {}
  200. }
  201. }
  202. }
  203. ```
  204. ### Goose
  205. In `~/.config/goose/config.yaml`:
  206. ```yaml
  207. extensions:
  208. hypr-computer:
  209. name: hypr-computer
  210. type: stdio
  211. cmd: uv
  212. args: [run, --quiet, --script, /home/USER/.local/share/hypr-computer/server.py]
  213. enabled: true
  214. timeout: 300
  215. ```
  216. ### Cline
  217. ```bash
  218. cline mcp add hypr-computer --yes -- uv run --quiet --script /home/USER/.local/share/hypr-computer/server.py
  219. ```
  220. In the IDE extension, use MCP Servers → Configure → Configure MCP Servers and
  221. add the following under `mcpServers`:
  222. ```json
  223. "hypr-computer": {
  224. "command": "uv",
  225. "args": ["run", "--quiet", "--script", "/home/USER/.local/share/hypr-computer/server.py"],
  226. "disabled": false,
  227. "autoApprove": []
  228. }
  229. ```
  230. ### Windsurf
  231. Use Cascade's "Open MCP config file" action. Which file it reads varies by
  232. build. Add the following under `mcpServers`, then press refresh:
  233. ```json
  234. "hypr-computer": {
  235. "command": "uv",
  236. "args": ["run", "--quiet", "--script", "/home/USER/.local/share/hypr-computer/server.py"]
  237. }
  238. ```
  239. ### Any other MCP client
  240. Register a **stdio** server named `hypr-computer`. Its command is `uv` and its
  241. arguments are `run --quiet --script /home/USER/.local/share/hypr-computer/server.py`.
  242. To shrink screenshots for a model with a smaller image limit, add
  243. `HYPR_COMPUTER_MAX_EDGE=<pixels>` to the server's environment.
  244. ## How it works, and why
  245. - **Screen**: `grim -s <factor>` captures the whole layout at a size the model
  246. won't downscale again. Screenshot pixels therefore map linearly onto layout
  247. coordinates, including on HiDPI and multi-monitor setups.
  248. - **Pointer**: Hyprland moves the cursor directly with
  249. `hyprctl dispatch 'hl.dsp.cursor.move({x=…,y=…})'`. Moving it with ydotool's
  250. relative motion would be distorted by pointer acceleration. ydotool then
  251. clicks wherever the cursor is.
  252. - **Shortcuts**: these go through `ydotool key` as evdev keycodes. Hyprland
  253. doesn't apply keybinds to key events from wtype's virtual keyboard.
  254. - **Text**:
  255. - ASCII is typed with `ydotool type`.
  256. - Non-ASCII runs are typed with `wtype`, led by a throwaway Shift tap.
  257. Chromium drops the first key that arrives after wtype uploads its keymap.
  258. - On non-US keyboard layouts, all text goes through wtype.
  259. - **Session discovery**: the server finds `WAYLAND_DISPLAY`,
  260. `HYPRLAND_INSTANCE_SIGNATURE` and the ydotool socket under `XDG_RUNTIME_DIR`.
  261. It therefore works even when the agent is started from SSH, tmux or a
  262. systemd unit.
  263. ## Limitations
  264. - Hyprland only. Pointer placement depends on `hyprctl`.
  265. - `key` uses US-layout physical key positions.
  266. - There's no accessibility tree. The model works from screenshots alone.
  267. - There are no per-app permissions or other safety layers beyond your client's
  268. tool-approval prompts. Approve actions carefully, and don't leave an agent
  269. unattended with sensitive apps open.
  270. ## Development
  271. ```bash
  272. uv run --no-project --with pytest --with 'mcp<2' pytest -q tests
  273. uv run --quiet --script server.py --check
  274. claude plugin validate . --strict
  275. ```
  276. ## Acknowledgements
  277. hypr-computer is a thin layer over these projects, and does nothing without them:
  278. | Project | Used for | License |
  279. | --- | --- | --- |
  280. | [Hyprland](https://github.com/hyprwm/Hyprland) (`hyprctl`) | Pointer placement, monitor and window info, input devices | BSD-3-Clause |
  281. | [grim](https://gitlab.freedesktop.org/emersion/grim) | Screenshots | MIT |
  282. | [ydotool](https://github.com/ReimuNotMoe/ydotool) | Clicks, scrolling, shortcuts and ASCII typing through uinput, and its `ydotoold` user service | AGPL-3.0 |
  283. | [wtype](https://github.com/atx/wtype) | Typing non-ASCII text through the Wayland virtual keyboard protocol | MIT |
  284. | [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) (`mcp`) | The MCP server (FastMCP) | MIT |
  285. | [uv](https://github.com/astral-sh/uv) | Running the server and installing its Python dependencies | MIT or Apache-2.0 |
  286. | [pytest](https://github.com/pytest-dev/pytest) | Tests (development only) | MIT |
  287. None of these are bundled or modified in this repo. The system tools are
  288. installed from your distribution's packages and run as separate programs. The
  289. Python packages are installed by `uv` when the server first starts. Each one
  290. stays under its own license.
  291. The packages were tested at Hyprland 0.56.2, grim 1.5.0, ydotool 1.0.4,
  292. wtype 0.4, mcp 1.30.0, uv 0.13.1 and pytest 9.2.0. The workflow was developed
  293. on [Omarchy](https://omarchy.org).
  294. ## License
  295. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.