Cua Hyprland Plugin on Omarchy

Cua Hyprland Plugin on Omarchy

cua-hyprland-plugin is an optional Hyprland plugin that gives Cua Driver compositor-native, multi-cursor input on Omarchy — so an AI agent can work in a background window without moving your pointer or stealing your focus.

TL;DR

omarchy pkg add cua-hyprland-plugin

It takes ~2 minutes (v0.33.2-3, ~243 KB). But know the critical framing first: this plugin is not a standalone app — it's one half of Cua Driver, the open-source (MIT) AI computer-use driver that lets agents click, type, and read screens on real machines. You install the plugin for the isolated input seats, and you install cua-driver (from cua.ai/driver/install.sh) to actually drive it via MCP.

Free forever (MIT). The plugin was built over a month directly with DHH, @SpencerGBull, and Hyprland author @vaxryy, announced 2026-09-25. On cua.ai's platform-support matrix, Hyprland/Omarchy is marked Experimental: "Qualified isolated input since 0.24.0 — Does not inherit Sway coverage."

Getting started (5 minutes)

1. Install.

omarchy pkg add cua-hyprland-plugin. This is the packaged route; the plugin is "off by default and outside the normal installer" for cua-driver, meaning the driver install script won't give you this — the Omarchy package is the intended path (it ships via the Omarchy Edge channel). (Confirm channel behavior on-machine — this is from cua.ai docs and the package description, not a live test.)

2. What the plugin does.

The compositor itself owns two independent agent seats — Cua-Agent and Cua-Agent-2 — and routes each seat's input to the right window. That's the whole trick: the agent gets its own painted cursor(s) and works in background windows while your own pointer stays free. No moving-the-visible-mouse tricks, no window-server workarounds.

3. Connect the driver.

Install cua-driver from the official route (/bin/bash -c "$(curl -fsSL https://cua.ai/driver/install.sh)" — downloads the binary and symlinks it to ~/.local/bin/cua-driver), then connect your agent: claude mcp add --transport stdio cua-driver -- cua-driver mcp, or use the computer-use compat mode cua-driver mcp --claude-code-computer-use-compat. Python and TS SDKs exist too. Health-check with cua-driver doctor, cua-driver status, cua-driver list_apps.

4. The three things everyone needs to know:

• The ABI constraint is the whole ballgame. Hyprland plugins compile against the compositor's internal headers — the plugin's Hyprland ABI and compiler toolchain must match the running compositor. That's why upstream release assets embed the Hyprland commit hash (cua-hyprland-plugin-0.36.0-6d6c734c…-build-kit.tar.gz) and the Omarchy package description reads "Cua input candidate for reviewed profile omarchy-edge-20261004-abi." A mismatched plugin can break Hyprland — the standard warning for all Hyprland plugins (hyprpm/hyprctl plugin load mechanics apply). The packaged route exists precisely to prevent this; don't hand-install a random tarball against your own Hyprland.
• Coverage is qualified, not general. As of the docs, qualified isolated input covers exactly two apps: LibreOffice Calc (libreoffice-fresh 26.2.5-3) and Inkscape (1.4.4-6) — the driver checks package metadata before every action. Not covered: Chromium, Electron, XWayland raw input; Unicode and IME; multiple layouts; modified pointer gestures. Native Wayland is opt-in via CUA_DRIVER_RS_ENABLE_WAYLAND=1; without it, Wayland sessions fall back to XWayland routes where the app has a real X11 window. AT-SPI (at-spi2-core) must be enabled and reachable on the session bus, or the driver loses the element tree.
• This is "computer use 2.0" infrastructure, not an app. The repo (trycua/cua, ~30k stars) also includes Cua Spaces (desktop VMs, incl. Omarchy images), Lume (local VM manager), Cua Bench (benchmarks), and CUA-S1 decision models. The plugin's job is narrow: isolated input seats. Bring your own agent and model — it speaks MCP, CLI (cua-driver call), or typed SDKs.

5. Where its config lives.

This is a compositor plugin, not a GUI app: no ~/.config/cua-hyprland-plugin to speak of (unconfirmed — the Omarchy packaged route handles loading; no documented hyprland.conf plugin {} snippet or hyprpm URL was found, and the docs flag packaged install/upgrade proof as "remaining work"). The driver's config paths are separate — check the driver README/docs for those. (Confirm on-machine; mark this section as uncertain.)

Common issues & fixes

Sourced from the real GitHub issues on trycua/cua (open as of 2026-10-18) — nothing invented. These are computer-use-edge issues, not package-manager problems.

Super+W (and all other Super shortcuts) from the agent arrive as plain letters

None of Omarchy's ~180 Super Hyprland bindings fire — driving an Omarchy guest from the Spaces viewer, Super+W arrived as w. Related: Wayland hosts don't request zwp_keyboard_shortcuts_inhibit_v1.

Fix: Open issue #5344 (Oct 2026): there is no user-side workaround in the issue thread — this is a protocol/inhibitor gap. If your agent needs Super bindings, it can't reliably send them yet. Watch #5344 and the companion feature #5345 ("Send ⌘ as Super" for the Mac viewer, which maps ⌘→Control today).

The viewer shows a black desktop on GNOME 50 Wayland

Open issue #5236 (Oct 2026): the driver has native-Wayland capture code (including Hyprland) but nothing for Mutter's ScreenCast portal, so it silently falls back to X11 capture of rootless Xwayland :0 and the viewer stays black.

Fix: On Hyprland/Omarchy specifically, native capture exists — this one bites GNOME 50 hosts. If you hit black-screen on Omarchy, check whether your capture path is falling back to X11 first.

Xwayland segfaults on startup and the whole session logs out when an agent tool runs

Open issue #5416 (Oct 2026): a winrects@cua helper active on Ubuntu 26.04/GNOME Shell 50.1 caused mutter's on-demand Xwayland to SIGSEGV — gnome-shell followed, user logged out, unsaved work lost.

Fix: Workaround: disable the winrects@cua helper. Cautionary tale: agent helpers touch the compositor; run experiments in a session you can afford to lose (Cua Spaces VMs exist for exactly this reason).

Driver can't see app UI structure — element tree missing

AT-SPI isn't enabled or reachable on the session bus.

Fix: Install at-spi2-core (Debian/Ubuntu/Fedora names from the README; check the Arch equivalent when verifying), enable toolkit accessibility (gsettings set org.gnome.desktop.interface toolkit-accessibility true on GNOME-based setups), and run cua-driver doctor. Without AT-SPI the driver sees X11 window info but loses the element tree.

hyprctl plugin load breaks Hyprland after a manual install

You loaded a plugin build whose Hyprland ABI/toolchain doesn't match the running compositor.

Fix: Use the packaged route (omarchy pkg add cua-hyprland-plugin) instead of hand-installed tarballs; the package pins against the reviewed edge ABI profile. This is the standard Hyprland plugin rule, not a Cua bug.

Pairs well with / If you hate this, try

Pairs well with

• cua-driver itself (the plugin is half of the pair), and Cua Spaces if you want the agent in a sandboxed Omarchy VM instead of on your live desktop. Claude Code or any MCP-capable agent as the driver client.

If you hate this, try

• hyprland-mcp (github.com/alderban107/hyprland-mcp) — an open-source MCP server for Hyprland with 27 tools (screenshot+OCR, click_text, mouse/keyboard via grim/wtype/ydotool, window management), installed via pipx and wired into Claude Code. It's agent-side tooling on top of Hyprland rather than a driver/compositor plugin — less isolated input, more hackable. Or Bytebot for a containerized-Linux-desktop agent if you want per-task sandboxed machines with logged before/after screenshots. The canonical reference is Anthropic's computer-use demo; Cua's pitch is the open-source, background-first alternative.

Comparison: cua-hyprland-plugin vs similar approaches

Verdict: Use the Cua plugin if you want true background, multi-cursor agent input on your live Omarchy desktop; use hyprland-mcp if you want MCP tools without touching the compositor; use Bytebot or a VM if the agent should never see your live session.