Prototype · Preview: every server in the official registry, synced every 30 minutes. Sign in with Google to write reviews.Prototype · updated every 30 min
PopNx MCPMCP servers for people who use AI · explained in plain words

Hyprland Computer Use

✓ smirnovlabs.com

by Smirnov-Labsversion 0.2.0i★ 0iRuns on your computerRepository ↗
Registry namecom.smirnovlabs/hypr-cua-mcp

How to install

What it does

Hyprland/Wayland computer-use MCP: grim screenshots + uinput click/type + hyprctl targeting

  • Connects Runs on your computer
  • Account or key No key needed
  • Category Other

Why it ranks here

Lists are ordered by a usage score (out of 100) built from these parts

Popularity0/80GitHub stars or weekly downloads: the larger counts 60, the smaller 20
Freshness12/12Full marks for a release or code change within 30 days
Still answering0/8The cloud endpoint answered at the last check
Usage score12/100

Quality: Passed 3/3 basic checks (shown, not used for ordering) · Momentum: No data yet (Used only on the Trending tab)

Install

Pick the AI app you use, then copy the settings.

Let your AI install it with one sentence

Please install Hyprland Computer Use. Follow https://mcp.popnx.com/i/smirnovlabs-hypr-cua-mcp.md, show me the commands and wait for my OK before running them.

Paste it into an AI that can work on your computer (such as Claude Code or Cursor). It reads our steps, shows you the commands and waits for your OK. No key, no sign-up. · See the full text your AI reads

Passed 3/3 checks · Runs on your computer · ✓ Commands checked Nov 14, 2026

First: which AI do you use?

Pick your app and the steps appear below.

Works with Claude, with some setup first

Install Python (uv) on your computer first (one time) · Only the Claude desktop app (Windows or Mac), not the web or phone

Let AI install it

Copy this message into a Claude chat. The AI checks your computer, tells you which file it will change, and waits for your OK every time.

Please install the MCP server Hyprland Computer Use for Claude on this computer, in this order: 1) Check uv with uv --version. If it is missing, tell me to install it from https://docs.astral.sh/uv/getting-started/installation/; do not install it yourself. 2) Use only this config (already checked by PopNx MCP): { "mcpServers": { "hypr-cua": { "command": "uvx", "args": [ "hypr-cua-mcp" ] } } } 3) Tell me the full path of the file you will change, or the command you will run, and wait for my OK. 4) No key is needed. 5) Do what we agreed, then check that the Hyprland Computer Use tools really show up.

This message has no key in it. If a key is needed, the AI will ask you to paste it yourself into the file or the app’s field.

  1. Install uv (if you don’t have it)

    Already installed? Check first · Open Terminal, type this command and press Enter

    uv --version
    • A version number such as uv … = installed, skip this step
    • "command not found" (on Windows: "is not recognized") = not installed yet, or installed but Terminal needs to be closed and reopened
    How to open Terminal

    Mac: press ⌘ + Space, type Terminal, press Enter

    Windows: open Start, type Windows PowerShell, then Open

    Not installed: uv has no click-through installer. Copy the one-line command for your system (macOS or Windows) from uv’s official page into Terminal · no separate Python install needed; uv downloads it when required

    Open the uv download page ↗

    When it’s done, close Terminal, open it again and run the same command. You should see a version number: uv --version

    Install once; it works for everything that needs uv

  2. Open the Claude desktop app’s settings file

    SettingsDeveloperEdit Config

  3. Paste these settings and save the file

    {
      "mcpServers": {
        "hypr-cua": {
          "command": "uvx",
          "args": [
            "hypr-cua-mcp"
          ]
        }
      }
    }
  4. Quit Claude and open it again

  5. Try it

    Use Hyprland Computer Use and tell me what you can do for me, then show me one thing

    ✓ If Claude says it is using Hyprland Computer Use or shows a Hyprland Computer Use tool in the answer, you are connected

Menu names checked against Anthropic’s help page on Nov 11, 2026 · your screen may differ slightly by app version

ChatGPT cannot connect Hyprland Computer Use yet

Hyprland Computer Use runs on your computer, but ChatGPT can only connect servers that run on the web

What you can do instead

A · Use an app that can connect Hyprland Computer Use

  • Install Python (uv) on your computer first (one time) · Only the Claude desktop app (Windows or Mac), not the web or phone
  • Install Python (uv) on your computer first (one time)
  • Install Python (uv) on your computer first (one time)
  • Install Python (uv) on your computer first (one time)

B · Others in Other that work with ChatGPT

Picked from the most used in the same category, only ones that connect by address with no key

Works with Claude Code, with some setup first

Install Python (uv) on your computer first (one time)

Let AI install it

Copy this message into a Claude Code chat. The AI checks your computer, tells you which file it will change, and waits for your OK every time.

Please install the MCP server Hyprland Computer Use for Claude Code on this computer, in this order: 1) Check uv with uv --version. If it is missing, tell me to install it from https://docs.astral.sh/uv/getting-started/installation/; do not install it yourself. 2) Use only this config (already checked by PopNx MCP): claude mcp add --scope user hypr-cua -- uvx hypr-cua-mcp 3) Tell me the full path of the file you will change, or the command you will run, and wait for my OK. 4) No key is needed. 5) Do what we agreed, then check that the Hyprland Computer Use tools really show up.

This message has no key in it. If a key is needed, the AI will ask you to paste it yourself into the file or the app’s field.

  1. Install uv (if you don’t have it)

    Already installed? Check first · Open Terminal, type this command and press Enter

    uv --version
    • A version number such as uv … = installed, skip this step
    • "command not found" (on Windows: "is not recognized") = not installed yet, or installed but Terminal needs to be closed and reopened
    How to open Terminal

    Mac: press ⌘ + Space, type Terminal, press Enter

    Windows: open Start, type Windows PowerShell, then Open

    Not installed: uv has no click-through installer. Copy the one-line command for your system (macOS or Windows) from uv’s official page into Terminal · no separate Python install needed; uv downloads it when required

    Open the uv download page ↗

    When it’s done, close Terminal, open it again and run the same command. You should see a version number: uv --version

    Install once; it works for everything that needs uv

  2. Open Terminal

    Mac: press Command+Space and type Terminal · Windows: open PowerShell

  3. Paste this command and press Enter

    claude mcp add --scope user hypr-cua -- uvx hypr-cua-mcp
  4. Type /mcp in Claude Code

    You should see Hyprland Computer Use listed as connected

  5. Try it

    Use Hyprland Computer Use and tell me what you can do for me, then show me one thing

    ✓ If Claude Code says it is using Hyprland Computer Use or shows a Hyprland Computer Use tool in the answer, you are connected

Menu names checked against Anthropic’s help page on Nov 11, 2026 · your screen may differ slightly by app version

Works with Cursor, with some setup first

Install Python (uv) on your computer first (one time)

Let AI install it

Copy this message into a Cursor chat. The AI checks your computer, tells you which file it will change, and waits for your OK every time.

Please install the MCP server Hyprland Computer Use for Cursor on this computer, in this order: 1) Check uv with uv --version. If it is missing, tell me to install it from https://docs.astral.sh/uv/getting-started/installation/; do not install it yourself. 2) Use only this config (already checked by PopNx MCP): { "mcpServers": { "hypr-cua": { "command": "uvx", "args": [ "hypr-cua-mcp" ] } } } 3) Tell me the full path of the file you will change, or the command you will run, and wait for my OK. 4) No key is needed. 5) Do what we agreed, then check that the Hyprland Computer Use tools really show up.

This message has no key in it. If a key is needed, the AI will ask you to paste it yourself into the file or the app’s field.

  1. Install uv (if you don’t have it)

    Already installed? Check first · Open Terminal, type this command and press Enter

    uv --version
    • A version number such as uv … = installed, skip this step
    • "command not found" (on Windows: "is not recognized") = not installed yet, or installed but Terminal needs to be closed and reopened
    How to open Terminal

    Mac: press ⌘ + Space, type Terminal, press Enter

    Windows: open Start, type Windows PowerShell, then Open

    Not installed: uv has no click-through installer. Copy the one-line command for your system (macOS or Windows) from uv’s official page into Terminal · no separate Python install needed; uv downloads it when required

    Open the uv download page ↗

    When it’s done, close Terminal, open it again and run the same command. You should see a version number: uv --version

    Install once; it works for everything that needs uv

  2. Click this button to open Cursor

    Open in Cursor

    Cursor asks you to confirm; click Install

  3. Open the AI chat in Cursor in Agent mode

  4. Try it

    Use Hyprland Computer Use and tell me what you can do for me, then show me one thing

    ✓ If Cursor says it is using Hyprland Computer Use or shows a Hyprland Computer Use tool in the answer, you are connected

Menu names checked against Cursor’s help page on Nov 11, 2026 · your screen may differ slightly by app version

Works with VS Code, with some setup first

Install Python (uv) on your computer first (one time)

Let AI install it

Copy this message into a VS Code chat. The AI checks your computer, tells you which file it will change, and waits for your OK every time.

Please install the MCP server Hyprland Computer Use for VS Code on this computer, in this order: 1) Check uv with uv --version. If it is missing, tell me to install it from https://docs.astral.sh/uv/getting-started/installation/; do not install it yourself. 2) Use only this config (already checked by PopNx MCP): { "servers": { "hypr-cua": { "type": "stdio", "command": "uvx", "args": [ "hypr-cua-mcp" ] } } } 3) Tell me the full path of the file you will change, or the command you will run, and wait for my OK. 4) No key is needed. 5) Do what we agreed, then check that the Hyprland Computer Use tools really show up.

This message has no key in it. If a key is needed, the AI will ask you to paste it yourself into the file or the app’s field.

  1. Install uv (if you don’t have it)

    Already installed? Check first · Open Terminal, type this command and press Enter

    uv --version
    • A version number such as uv … = installed, skip this step
    • "command not found" (on Windows: "is not recognized") = not installed yet, or installed but Terminal needs to be closed and reopened
    How to open Terminal

    Mac: press ⌘ + Space, type Terminal, press Enter

    Windows: open Start, type Windows PowerShell, then Open

    Not installed: uv has no click-through installer. Copy the one-line command for your system (macOS or Windows) from uv’s official page into Terminal · no separate Python install needed; uv downloads it when required

    Open the uv download page ↗

    When it’s done, close Terminal, open it again and run the same command. You should see a version number: uv --version

    Install once; it works for everything that needs uv

  2. Click this button to open VS Code

    Open in VS Code

    VS Code asks you to confirm; click Install

  3. Open the AI chat in VS Code in Agent mode

  4. Try it

    Use Hyprland Computer Use and tell me what you can do for me, then show me one thing

    ✓ If VS Code says it is using Hyprland Computer Use or shows a Hyprland Computer Use tool in the answer, you are connected

Menu names checked against VS Code’s help page on Nov 11, 2026 · your screen may differ slightly by app version

Other apps that use MCP, such as Windsurf, Zed or Gemini CLI, each add servers differently. See how in the app list.

See every app that uses MCP →

JSON settings are under “For developers” below

Stuck? Ask people who use Hyprland Computer Use💬 Discussion →
For developers: Terminal commands and JSON settings

Installed on your computer

Claude Code

claude mcp add --scope user hypr-cua -- uvx hypr-cua-mcp

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "hypr-cua": {
      "command": "uvx",
      "args": [
        "hypr-cua-mcp"
      ]
    }
  }
}

Cursor (~/.cursor/mcp.json)

{
  "mcpServers": {
    "hypr-cua": {
      "command": "uvx",
      "args": [
        "hypr-cua-mcp"
      ]
    }
  }
}

VS Code (mcp.json)

{
  "servers": {
    "hypr-cua": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "hypr-cua-mcp"
      ]
    }
  }
}

These settings are generated from the maker’s registry entry. If the README says otherwise, follow the README.

At a glance

Downloads per weeki
133/wk
Verified domain
✓ smirnovlabs.com
Connection
Runs on your computer
Latest versioni
0.2.0
Categoryi
Other
Published to registryi
Nov 7, 2026
Code last changedi
Nov 7, 2026
Maker
Smirnov-Labs
Packages
pypi: hypr-cua-mcp
Website
github.com
Registry status
Active

Which apps can use it

Based on how this server connects and on each app’s own docs, checked Nov 10, 2026.

Run on your computer in

ClaudeGooseLM StudioMsty StudioCherry StudioCursorVS Code + GitHub CopilotVisual StudioWindsurf (Devin Desktop)ZedKiroClineContinueJetBrains AI AssistantClaude CodeCodex CLIGemini CLIOpenCodenodecodeWarpLibreChatRaycast

All apps, with pros and cons →

Related guides

What it can do

Runs on your computer; the tool list appears in your AI app after you install it.

Basic checksi

We check information anyone can see; we have not read the code. Checks that do not apply are left out of the count. · Checked Nov 20, 2026

  • ✓ Pass

    Maker matches the repo

    The registry name was verified against the domain smirnovlabs.com (the registry checks domain ownership)

  • ✓ Pass

    Still maintained

    Code last changed 13 days ago

  • ✓ Pass

    Has a licence

    Uses MIT

  • – Not applicable

    Endpoint responds

    This one runs on your computer; there is no internet endpoint

  • – Not applicable

    Sign-in with OAuth

    Runs on your computer and uses local settings instead

  • … Not checked yet

    No hidden instructions in tool descriptions

    Runs on your computer; we can only read tool lists from internet endpoints

Published vulnerabilities (OSV.dev)

No entries on OSV.dev for hypr-cua-mcp@0.2.0

Checks only this package version, not every dependency · checked Nov 15, 2026

What we check → · JSON

Makers: ask for a re-check or report wrong info
For makers: add a badge to your README

If you made this, paste this code into your README. The badge links back to this page.

[![Featured on PopNx MCP](https://mcp.popnx.com/badge/smirnovlabs-hypr-cua-mcp.svg)](https://mcp.popnx.com/en/servers/smirnovlabs-hypr-cua-mcp)

Discussion

Ask, share a tip or report that it does not work. Sorted by what people marked helpful.

No posts yet. Be the first to ask or share.

Posts here are written by users, not the PopNx team.

Sign in to post

User reviews

No reviews yet

Sign in to write a review

Compared with others in Otheri

  • More stars than 0% of the other 20815 servers in this category
  • Published to the registry more recently than 79% of the other 20815 servers in this category
  • Basic checks equal to or better than 99% of the other 20815 servers in this category

Compared with every active server in this category in the registry. Stars count only when the publisher owns the repo.

Common questions

Is Hyprland Computer Use safe?

It passed 3 of 3 applicable basic checks. We have not read the code. Before adding a key or token, see what access the server asks for and use a key with only the permissions you need.

What keys or codes does it need?

The registry does not list a required key, though some servers ask you to sign in on first use.

Does it run on my computer or in the cloud?

It runs on your computer. Your AI app starts it when needed, and data does not pass through the maker’s servers (unless it calls an online service itself).

Is it still maintained?

The GitHub repo last changed 13 days ago, and the latest version (0.2.0) reached the registry 13 days ago.

Which apps can use it?

Apps that support MCP, such as Claude Desktop, Claude Code, Cursor and VS Code. You also need Python (uv) on your computer.

What can I use instead?

In the same category: World Monitor, openstatus, Oh My Posh Validator, Strata, Jitsu

Similar alternatives

Same category, other makers, commands already checked. Official ones first, then by stars.

Reading a card:↓ Downloads per weeki★ GitHub starsiThree pillars: reviews · checks · usageiUpdated = latest version published to the registryi

World Monitor

Real-time global intelligence on conflict, markets, energy, trade, shipping and cyber. 100 tools.

by koala73Widely used★ 90.9KUpdated 4 days ago

Runs in the cloud✓ service owner · worldmonitor.app

openstatus

Manage monitors, status pages, incidents and maintenances in your openstatus workspace.

by openstatusHQWidely used★ 9.3KUpdated 2 months ago

Runs in the cloud✓ service owner · openstatus.dev

Oh My Posh Validator

Validate oh-my-posh configurations and segment snippets against the official schema.

by JanDeDobbeleerWidely used★ 23.8K Stars for the whole repoUpdated 31 days ago

Runs in the cloud✓ service owner · ohmyposh.dev

Strata

MCP server for progressive tool usage at any scale (see https://klavis.ai)

by Klavis-AIGrowing★ 5.8KUpdated 14 months ago

Runs in the cloudRepo archived✓ klavis.ai

Jitsu

Manage Jitsu data pipelines: destinations, streams, connections, functions, live events.

by jitsucomWidely used★ 5.1KUpdated 4 months ago

Runs in the cloud✓ service owner · jitsu.com
Compared with similar ones
This one
Hyprland Computer Use
World MonitoropenstatusOh My Posh ValidatorStrataJitsu
Runs whereInstalls on your computerRuns in the cloud, nothing to installRuns in the cloud, nothing to installRuns in the cloud, nothing to installRuns in the cloud, nothing to installRuns in the cloud, nothing to install
Needs a keyNoNoNoNoNoNo
Add with + in ClaudeNoNoNoNoNoNo
Basic checks3/34/44/44/41/44/4
LicenseMITAGPL-3.0AGPL-3.0MITApache-2.0MIT
PriceNo cost listed in the registryNo cost listed in the registryNo cost listed in the registryNo cost listed in the registryNo cost listed in the registryNo cost listed in the registry

README from the maker

Open the README

Copied from the maker’s repo as written. PopNx MCP has not reviewed or endorsed it. HTML, images and scripts are removed. Links lead off this site.

hypr-cua-mcp

A Hyprland/Wayland computer-use MCP server. It gives an MCP client (Claude Code, etc.) the ability to *see* your desktop, *understand* it via the Hyprland tree, and *drive* it with mouse + keyboard. It runs locally over stdio.

Why this exists: generic Linux computer-use servers are blind to the compositor — they hand the model a giant multi-monitor screenshot and hope its pixel guesses land. This server crops to one output (or one window) with grim, downscales to the vision-API budget, and exposes hyprctl's tree so the model targets windows by identity, not luck. Coordinates are always given *in the screenshot the model was just shown*; the server maps them back to global layout pixels.

Built for Wayland/Hyprland: grim (capture) + a self-owned uinput device (input) + hyprctl (tree/control) + wl-clipboard. It is the Wayland successor to i3-computer-use-mcp (X11).

Tools

Window ids are Hyprland addresses (0x…) from list_windows — not integers.

See

ToolWhat it does
list_windowsEvery Hyprland window: id (address), class, title, workspace, output, global rect, floating/focus/visibility
get_outputsActive monitors: global geometry, scale, workspace
screenshot(output?)Screenshot one output (default: focused), downscaled to the API budget
screenshot_window(con_id)Full-res crop of a single window (by address) — best for small text
get_mouseCurrent global pointer location

Act

ToolWhat it does
click / double_click / move_mouse / drag / scrollPointer actions; coords in a screenshot's pixel space (pass its frame_id). move_mouse(follow=True) also focuses the window under the pointer
type_text(text, con_id?) / key(keys, con_id?)Keyboard input; with a con_id, focus that window first and refuse to type if focus doesn't land
read_clipboard(selection?) / write_clipboard(text, selection?, secret?)Exact text in/out of the clipboard/primary selection (no OCR); write returns only a length, never the value

Control Hyprland (needs a Lua config, see Requirements)

ToolWhat it does
focus_window(con_id)Focus a window by address (best-effort; see the follow_mouse caveat under Safety)
launch(command)Launch an app via Hyprland's exec dispatcher
goto_workspace(ws) / move_window_to_workspace(con_id, ws)Switch to / move a window (by address) to a workspace
set_floating(con_id, enable?)Toggle a window's floating state
layout_message(message)Send a message to the active layout engine (e.g. togglesplit)
run_dispatch(dsp_expr)Raw Hyprland dispatcher escape hatch (exit blocked)

Work off-screen (no window, no focus stolen)

ToolWhat it does
tmux_list / tmux_new / tmux_run / tmux_keys / tmux_read / tmux_killDrive terminals in detached tmux sessions on an isolated hypr-cua socket; it never touches your own tmux sessions
task_start / task_status / task_list / task_send / task_stopRun a command as a background task and poll it (running → done + exit code); answer prompts with task_send
cdp_targets / cdp_open / cdp_navigate / cdp_read / cdp_eval / cdp_screenshot / cdp_click / cdp_type / cdp_closeDrive Chrome tabs over the DevTools protocol, never your main profile (see Browser channel)

The coordinate model (the important bit)

The Hyprland tree uses global layout pixels spanning all monitors. Screenshots are cropped + downscaled, so every screenshot records a mapping frame (region origin + per-axis scale). Pointer tools accept coordinates *in the screenshot's pixel space* and translate them:

global_x = region.x + screenshot_x / scale_x

global_y = region.y + screenshot_y / scale_y

Practically: take a screenshot (it returns a frame_id), then call click(x, y, frame_id=…) with the pixel you see in *that* image. Pointer tools reject a stale or unknown frame_id rather than guessing against the wrong one. Without a frame_id, they use your latest screenshot.

The uinput pointer positions absolutely: global pixels map to the device's abs axes via the layout extent read from hyprctl monitors (verified ~1px).

Requirements

  • Hyprland on Wayland. Developed and tested on Hyprland 0.56 across three monitors at scale 1.
  • A Lua config (`hyprland.lua`, Hyprland 0.55+) for the window-control tools. These tools go through hyprctl eval and Hyprland's Lua hl.dispatch API: focus_window, launch, goto_workspace, move_window_to_workspace, set_floating, layout_message, run_dispatch, plus type_text/key with a con_id and move_mouse(follow=True). Everything else works with any config: screenshots, pointer and keyboard input, the window tree, the clipboard, and the tmux/task/browser channels.
  • Read-write access to `/dev/uinput` for mouse and keyboard input (see below).
  • Python 3.11+ and uv.
  • It runs inside your Hyprland session: it needs WAYLAND_DISPLAY, XDG_RUNTIME_DIR and HYPRLAND_INSTANCE_SIGNATURE from the environment. MCP clients launched from your desktop pass these through.

Install the dependencies

The server shells out to a handful of CLI tools. screenshot needs grim, the clipboard tools need wl-clipboard, and everything reads/drives Hyprland through hyprctl; tmux and a Chromium/Chrome are only needed for the optional terminal and browser channels.

ToolNeeded forArchDebian/Ubuntu
hyprctltree + control (required)bundled with hyprlandbundled with hyprland
grimscreenshot / screenshot_window (required)pacman -S grimapt install grim
wl-clipboardread_clipboard / write_clipboardpacman -S wl-clipboardapt install wl-clipboard
uvruns the server + syncs Python depspacman -S uvsee astral.sh/uv
tmuxtmux_* / task_* tools (optional)pacman -S tmuxapt install tmux
Chromium / Chromecdp_* browser tools (optional)pacman -S chromiumapt install chromium

Arch, in one go (Hyprland assumed already installed):

sudo pacman -S grim wl-clipboard uv tmux chromium

Input uses a self-owned uinput device, so the process needs read-write on /dev/uinput. It needs no root and no ydotoold. Run getfacl /dev/uinput. If it lists your user with rw (typically through a uaccess udev rule), you're set. If not, add a rule that grants access to the user logged in at the seat:

echo 'KERNEL=="uinput", SUBSYSTEM=="misc", TAG+="uaccess", OPTIONS+="static_node=uinput"' \

| sudo tee /etc/udev/rules.d/60-hypr-cua-uinput.rules sudo udevadm control --reload && sudo udevadm trigger

The Python deps (mcp, pillow, evdev, websocket-client) are synced by uv on first launch.

Miss one and the matching tool says so: calling screenshot without grim returns *"grim not found; install it …"* straight to the model, so it can tell you what to install instead of failing on a cryptic traceback.

Register with your MCP client

It's a local stdio server. The client starts it on demand, and you don't need a clone.

Claude Code:

claude mcp add hypr-cua -- uvx hypr-cua-mcp

Clients with an `mcpServers` JSON config (Cursor, Gemini CLI, Cline, …):

{

"mcpServers": { "hypr-cua": { "command": "uvx", "args": ["hypr-cua-mcp"] } } }

Codex CLI (~/.codex/config.toml):

[mcp_servers.hypr-cua]

command = "uvx" args = ["hypr-cua-mcp"]

From a local checkout: the wrapper syncs deps on first launch. When a shared server is running, the wrapper connects to it.

claude mcp add hypr-cua -- /path/to/hypr-computer-use-mcp/bin/hypr-cua-mcp

Reconnect your client (in Claude Code: /mcp → reconnect) to pick up the server. Smoke-test the plumbing first (read-only, no clicks):

uvx hypr-cua-mcp --selftest

One shared server per login

By default each MCP client session starts its own hypr-cua. From a checkout you can run one shared server per desktop login instead. A session then connects in about 20 ms and costs about 17 MB instead of about 94 MB. bin/hypr-cua-mcp connects to the shared server when it runs. When it doesn't, the wrapper starts a stdio server for the session, so the registration stays the same.

  1. Install the units. Run this in the checkout:
   uv sync

mkdir -p ~/.config/systemd/user cp contrib/systemd/hypr-cua.socket ~/.config/systemd/user/ sed "s|@CHECKOUT@|$PWD|" contrib/systemd/hypr-cua.service > ~/.config/systemd/user/hypr-cua.service systemctl --user daemon-reload

  1. Start the socket from your Hyprland startup, so each new server gets the current session's variables. In hyprland.lua, inside your startup handler:
   hl.exec_cmd("systemctl --user import-environment DISPLAY WAYLAND_DISPLAY HYPRLAND_INSTANCE_SIGNATURE XDG_CURRENT_DESKTOP; systemctl --user stop hypr-cua.service; systemctl --user restart hypr-cua.socket")

Run the same command in a terminal once to start it without logging out.

  1. Reconnect your MCP sessions (in Claude Code: /mcp → reconnect).

To upgrade, run git pull && uv sync && systemctl --user restart hypr-cua.service. Open sessions reconnect by themselves. A call that was running during the restart fails once with a message that it may have completed. The restart also ends hypr-cua's tmux sessions and tasks.

Sessions share the server's browser. Its HYPR_CUA_CDP_* settings come from the service's Environment= lines, not from the client. Screenshots stay per session: the server rejects another session's frame_id as stale.

Browser channel

The cdp_* tools drive Chrome or Chromium tabs over the DevTools protocol, so browser work needs no window focus. They never open your main profile.

The first cdp_* call picks a browser, and later calls keep it while it stays up:

  1. If a browser answers on port 9222, the tools attach to it. Run your automation profile there to keep logins.
  2. Otherwise they start a private headless Chrome with a throwaway profile. Chrome picks a free port, so it never collides with 9222. It stops after 10 minutes without a call, and when the server exits.

cdp_targets reports which one is in use, "browser": "automation" or "private". All sessions of one server share that browser, its tabs and its cookies.

For logins that persist, start a dedicated automation profile on port 9222. From a checkout, bin/hypr-cua-chrome does that. Otherwise run:

chromium --user-data-dir="$HOME/.local/share/hypr-cua-chrome" \

--remote-debugging-port=9222 --no-first-run --no-default-browser-check

Log in only to what you're happy to automate. Any local process that can reach a DevTools port can drive that browser, and that includes the private one.

cdp_open and

Only the beginning is shown; read the rest in the repo