Skip to content

feat(drivers): cua-driver on Omarchy: its install, Omarchy's shortcuts in the computer skill, and a Hyprland crash as an infra failure - #568

Merged
earakely-scale merged 2 commits into
mainfrom
edgararakelyan/cua-driver-omarchy-install
Nov 9, 2026
Merged

earakely-scale merged 2 commits into
mainfrom
edgararakelyan/cua-driver-omarchy-install

Conversation

@earakely-scale

@earakely-scale earakely-scale commented Nov 9, 2026 •

Copy link
Copy Markdown
Collaborator

Part of FD-5341 (O4). The branch is named without the issue id, so merging won't close it: O4's "done when" needs a composed Omarchy disk, which is O1's.

It follows the O1 decisions settled on FD-5338: D8 puts the plugin in the base, and D10 makes a crash an infrastructure failure.

What changes

cua-driver's Omarchy install (drivers/envs/cua-driver/):

  • supports gains {"os": {"type": "linux", "distribution": ["omarchy"], "display": ["wayland"]}, "arch": ["amd64"]}.
  • A new [install."linux/omarchy"] in env.toml. It installs requirements-omarchy.txt (the protocol, cua-driver==0.44.0, which is the Hyprland pin EXECUTABLES["hyprland/amd64"] checks, and python-xlib, which driver.py imports on any Linux) and the same two services as Linux.
  • No Hyprland plugin and no pacman: per D8, Omarchy's base carries the plugin, so this needs nothing from O2's pacman half.
  • No cua-driver telemetry disable step: every cua-driver invocation the driver makes (the daemon, the manifest, the skill pack) already runs with telemetry and update checks off by environment.

Omarchy's shortcuts in the computer skill (protocol computer/skill.py). SHORTCUTS is now keyed by platform, using entry_for as O2 keys installs: a distribution's entry replaces its OS type's. The Linux entry would otherwise have told an Omarchy agent that Alt+Tab switches windows and Alt+F4 closes one. Omarchy's entry lists its Super chords:

  • workspaces;
  • tiling: focus, move, close, full screen, float;
  • the terminal, file manager, browser, the app launcher, Omarchy's menu and the shortcut list;
  • universal copy and paste;
  • the usual app chords.

cua-driver's notes on Hyprland (hyprland.NOTES) tell agents that only Super chords reach the desktop's shortcuts. Every other chord goes to the focused window, so Alt+Tab doesn't fire.

A Hyprland crash becomes an infrastructure failure. After a crash, Hyprland's watchdog brings it back within the same session, in safe mode with no plugins and under a new instance signature. Nothing restarts the driver with it.

  • When another Hyprland runs in place of the one the driver started with (hyprctl -j instances), the cua-driver plugin check fails with final=True.
  • Every input then fails as device_unavailable: "Hyprland restarted under this driver, as its watchdog does after a crash, in safe mode with no plugins, so the computer can't take input again: an infrastructure failure".
  • If Hyprland simply doesn't answer and nothing has replaced it, the check fails but isn't final.

FD-5408 is the framework half: it makes a turn on a computer with a final check an infra_error.

Maintainability (second commit, 73a44c6)

  • One desktop key (_desktop(): macos, windows, hyprland, or none for X11) now picks both cua-driver's manifest (mcp-<desktop>.json) and its executable's pin (<desktop>/<arch>). Before, two hand-written chains had to agree.
  • Omarchy's shortcuts reuse Linux's app chords (_LINUX_APPS) instead of repeating them. Linux's text is byte-for-byte unchanged.
  • The Omarchy install's test checks for an exact cua-driver==<version> pin, not 0.44.0, so a version bump doesn't touch it.
  • The drivers README's Hyprland section is split into four paragraphs: install, input, keymap reset, and readiness. The text is unchanged.

These are behaviour-neutral, so the VM run below still stands.

Follow-up filed: FD-5410 moves the shortcut list into the computer's base, so each base version owns its own binds and the protocol doesn't collect distribution prose.

Verified on an Omarchy 4.5.0 VM

The stock qcow2 booted on OVMF with virtio-vga, the plugin from Omarchy's repo, and the driver installed from requirements-omarchy.txt with this branch's protocol wheel, running as systemd user units. fcitx5 was running.

  • Full probe: 47 passed, 0 failed, 1 not applicable (P8). Keyboard matrix V1–V6: all pass.

  • The computer skill reads "Omarchy 4.5.0 (amd64), a Wayland session (Hyprland)", with Omarchy's shortcuts and cua-driver's note. There's no Alt+Tab; F4 appears only in the list of key names.

  • Every shortcut the skill names, pressed through computer_key, does what it says. All pass:

    Shortcut Result
    Super+Enter opens a terminal (foot)
    Super+ArrowLeft focuses the window to the left
    Super+Shift+2 moves the window to workspace 2
    Super+2 switches to workspace 2
    Super+w closes the window
    Super+f full screen
    Super+t floats the window
    Super+Space opens Omarchy's menu
    Super+k opens the shortcut list
    Super+Alt+Space opens the app launcher

    In the launcher, typing xyz, three Backspaces, foot and Enter started foot, so Backspace edits there.

  • Crash: kill -SEGV on Hyprland brought it back in --safe-mode. computer-ready then reported the plugin check {"ok": false, "detail": "Hyprland restarted under this driver, …: an infrastructure failure", "final": true}, and computer_key failed with that message.

Tests

  • tst/unit/drivers/, packages/agentenv-protocol/tests/test_computer_driver.py and the shipped-bundle checks pass, 150 tests.
    • Readiness after a restart under the driver is final, while one that only doesn't answer isn't. Input then fails as an infrastructure failure, sending nothing.
    • Loaded in a Hyprland session, the driver pins mcp-hyprland.json and has its notes; on X11 it has neither.
    • An Omarchy base gets requirements-omarchy.txt with the Linux services, Ubuntu keeps requirements.txt, and supports includes Omarchy's platform.
    • An Omarchy computer's skill has Omarchy's shortcuts and no Alt+Tab.
  • With tst/unit/bundle/shipped_bundles_test.py, tst/unit/env/envs and the whole protocol package: 2305 passed. The one failure, test_disk_recipe::…windows_install…, fails the same way on main locally.
  • ruff check is clean.

🤖 Generated with Claude Code

RetriggerView in GreptileConfidence Score: 5/5

The PR appears safe to merge; the remaining note about keyboard delivery is non-blocking.

Fix All in CursorFindings

  1. P2 Notes omit keyboard delivery exceptions ▶
Fix with agent prompt
### Issue 1
src/agent_env/drivers/envs/cua-driver/hyprland.py:44-45
`NOTES` says every chord without Super goes to the focused window. But `_press_on_hyprland` sends it to the desktop when no window is focused or a menu holds the keyboard. Mention those exceptions so agents know ordinary keys can still reach menus and the empty desktop.

```suggestion
NOTES = ("Keys held with Super go to the desktop, where its shortcuts take them. Other keys and chords go to the "
         "focused window, bypassing desktop shortcuts such as Alt+Tab. When no window is focused or a menu holds the "
         "keyboard, they go to the desktop instead.")
```

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

Adds an Omarchy install for cua-driver, Omarchy shortcuts in the computer skill, and a final readiness failure after Hyprland restarts.

  • Omarchy Wayland computers can install and run cua-driver.
  • Omarchy computer skills show the shortcuts agents can use on its desktop.
  • A replaced Hyprland session now ends computer input as an infrastructure failure.
  • The driver uses one desktop key for its manifest and executable pin.

Reviews (5) · Last reviewed commit: "refactor(drivers): one desktop key for c..." · Reviewed by Greptile

…s in the computer skill, and a Hyprland crash as an infrastructure failure

cua-driver's supports names Omarchy's Wayland desktop on amd64, which installs [install."linux/omarchy"]:
requirements-omarchy.txt, with cua-driver at Hyprland's own pin (0.44.0), and the two services; Omarchy's base carries the
Hyprland plugin.

The computer skill's shortcuts are keyed by platform, a distribution's replacing its OS type's, and Omarchy's are its
Super chords: workspaces, tiling, the launcher, its menu and its universal copy and paste. On Hyprland cua-driver's notes
say that only Super chords reach the desktop's shortcuts.

When another Hyprland runs in place of the one the driver started with, as Hyprland's watchdog brings one back in safe
mode after a crash, the plugin check fails for good (final) and every input fails as an infrastructure failure.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@earakely-scale
earakely-scale requested a review from a team as a code owner November 9, 2026 18:27
@socket-security

socket-security Bot commented Nov 9, 2026 •

Copy link
Copy Markdown

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff Package Supply Chain
Security
Vulnerability Quality Maintenance License
Addedpypi/​cua-driver@​0.44.099100100100100

View full report

Comment on lines +44 to +45
NOTES = ("Keys held with Super go to the desktop, where its shortcuts take them; every other key or chord goes to the "
"focused window, so a desktop shortcut without Super, such as Alt+Tab, doesn't fire.")

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Notes omit keyboard delivery exceptions

NOTES says every chord without Super goes to the focused window. But _press_on_hyprland sends it to the desktop when no window is focused or a menu holds the keyboard. Mention those exceptions so agents know ordinary keys can still reach menus and the empty desktop.

Suggested change
NOTES = ("Keys held with Super go to the desktop, where its shortcuts take them; every other key or chord goes to the "
"focused window, so a desktop shortcut without Super, such as Alt+Tab, doesn't fire.")
NOTES = ("Keys held with Super go to the desktop, where its shortcuts take them. Other keys and chords go to the "
"focused window, bypassing desktop shortcuts such as Alt+Tab. When no window is focused or a menu holds the "
"keyboard, they go to the desktop instead.")
Prompt To Fix With AI
This is a comment left during a code review.
Path: src/agent_env/drivers/envs/cua-driver/hyprland.py
Line: 44-45

Comment:
**Notes omit keyboard delivery exceptions**

`NOTES` says every chord without Super goes to the focused window. But `_press_on_hyprland` sends it to the desktop when no window is focused or a menu holds the keyboard. Mention those exceptions so agents know ordinary keys can still reach menus and the empty desktop.

```suggestion
NOTES = ("Keys held with Super go to the desktop, where its shortcuts take them. Other keys and chords go to the "
         "focused window, bypassing desktop shortcuts such as Alt+Tab. When no window is focused or a menu holds the "
         "keyboard, they go to the desktop instead.")
```

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

Fix in Cursor Fix in Claude Code Fix in Codex

…x app chords, and the Hyprland docs by topic

cua-driver's manifest and its executable's pin are now chosen by one desktop key (macos, windows, hyprland, or none for
X11) instead of two chains that had to agree. Omarchy's shortcuts reuse Linux's app chords rather than repeating them,
the Linux text unchanged. The Omarchy install's test checks for an exact cua-driver pin, not a version, and the drivers
README's Hyprland section is split into its install, its input, its keymap reset and its readiness.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@earakely-scale
earakely-scale merged commit 0ec4652 into main Nov 9, 2026
38 checks passed
@earakely-scale
earakely-scale deleted the edgararakelyan/cua-driver-omarchy-install branch November 9, 2026 19:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant