Skip to content

feat(drivers): cua-driver 0.44 on Hyprland, keys to the focused window and text to the desktop - #559

Merged
earakely-scale merged 3 commits into
mainfrom
edgararakelyan/cua-driver-hyprland-key-routing
Nov 9, 2026
Merged

earakely-scale merged 3 commits into
mainfrom
edgararakelyan/cua-driver-hyprland-key-routing

Conversation

@earakely-scale

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

Copy link
Copy Markdown
Collaborator

Part of FD-5362 (O4.1). Branch named without the issue id, so merging won't close it.

What changes

On a Hyprland desktop (Omarchy), cua-driver's driver:

  • Runs cua-driver 0.44.0, its own pin. 0.38.0 refuses background input on Hyprland (client_not_qualified), and background is the default delivery for cua-driver's own tools. computer-ready checks 0.44.0's wheel executable (EXECUTABLES["hyprland/amd64"]) and the tools in mcp-hyprland.json. That manifest was captured from 0.44.0's cua-driver mcp on Omarchy: the same 66 tools, instructions and 11 resources as 0.38, but different schemas for click, set_config, start_recording and type_text. The other desktops stay on 0.38.0.

  • Sends text to the desktop. It goes in the foreground, where Hyprland's shortcuts, a menu holding the keyboard and non-ASCII text all work. The window path refuses non-ASCII text and refuses anything while a menu holds the keyboard.

  • Sends keys to the focused window. It goes in the foreground, where Backspace, the arrows, Home/End and Ctrl+A edit text the way a person's keys do. At the desktop they do nothing in a text box. Keys are pressed as on a US keyboard, so a shifted character goes as Shift plus the key it's on. The plugin only takes a US layout's keys there: it refuses ! ("no evdev mapping") and types A as a.

  • Falls back to the desktop for:

    • Super and keys held with it, which are Hyprland's own shortcuts. The window path would type them into the app.
    • a key pressed with nothing focused;
    • a key the window path refuses with foreground_grab because a layer such as Omarchy's menu holds the keyboard.

    At the desktop, punctuation goes by its keysym name. Given the raw character, cua-driver falls back to libei, which hangs its input worker.

Any other refusal on the window path still fails as delivery_failed.

Not in this PR (left for O1/O4): the Omarchy supports entry, and an [install."linux/omarchy"] that installs 0.44.0. A Hyprland computer currently installs 0.44.0 itself.

Omarchy's fcitx5: the keymap is put back, and fcitx5 stays on

Stock Omarchy runs the fcitx5 input method (omarchy-fcitx5.service). It also turns Omarchy's Shift+CapsLock compose sequences into text, so we keep it running.

The problem. fcitx5's virtual keyboard copies the keymap that cua-driver uploads for desktop text, and hyprctl devices then reports active_keymap: error. From then on cua-driver refuses every key aimed at a window (foreground_unavailable (unsupported_layout)). Without the fix, the probe on stock Omarchy gets 45/47.

The fix. When the window path refuses a key with unsupported_layout, the driver:

  1. makes sure Hyprland has SUPER + CTRL + ALT + SHIFT + F12 bound to nothing, binding it through hyprctl eval 'hl.bind(...)' if not;
  2. presses that chord at the desktop;
  3. sends the key to the window again, retrying for up to a second.

The chord's keys are all US-layout keys, so cua-driver sends it with the US keymap, and fcitx5 copies that in turn. Hyprland consumes the chord as its bind, so no window receives it. The bind has no description, so Omarchy's keybindings menu doesn't list it.

The driver presses the chord only while its own bind alone has it. It remembers the bind it made, as Hyprland lists it (__lua and the function's number). In every other case the key fails as cua-driver refused it, with a hint saying why, and no chord is pressed:

  • someone else's bind on the chord;
  • ours plus another bind;
  • a bind left by an earlier driver process;
  • a bind that can't be made.

If the chord has no bind, as after a config reload, the driver binds it again.

What else I tried, on a VM with fcitx5 running:

Approach Result
fcitx5-remote -s keyboard-us, -r, -c/-o, -t; D-Bus ReloadAddonConfig waylandim and SetCurrentIM Keymap stayed broken.
Restarting omarchy-fcitx5.service Restored it, but took 1.5 s each time.
Shift+F12 or Ctrl+A at the desktop Restored it, but the app received the keystroke.
The bound no-op chord Restored it in 0.07 s, 3 out of 3 times, and the app received nothing.
ASCII text sent through the window path instead Left the keymap alone, but a Tab broke the call partway (text_interrupted) and a newline was dropped. Text therefore stays at the desktop, where Tab, Enter, Unicode and menus already work.

Verified

On an Omarchy 4.5.0 VM: the stable qcow2 booted on OVMF and Limine with virtio-vga, Hyprland 0.56.2-4, cua-hyprland-plugin 0.33.2-3, cua-driver 0.44.0 from PyPI, and this branch's driver running as systemd user units. fcitx5 was running throughout.

  • Full probe (python -m agentenv_protocol.computer.conformance … --level full): 47 passed, 0 failed, 0 unverified, 1 not applicable (P8, no leasing). Before the keymap reset it was 45/47 with fcitx5 running.

  • Keyboard matrix through computer_* on the GTK desk:

    Check What it covers
    V1 text reaches the focused window
    V2 Ctrl+A then Backspace clears the field
    V3 all 32 ASCII punctuation keys type exactly
    V4 Super+2 / Super+1 switch workspaces
    V5 text typed with Omarchy's menu open goes to the menu, and Escape closes it
    V6 typing on an empty workspace answers and stays out of the desk; Super+1 returns

    All six checks pass.

  • On a freshly booted session, with no bind yet: the driver made the reset bind itself, once. There was 1 bind after the keyboard matrix and still 1 after the probe, and both passed again.

  • After a driver-only restart, the bind the old process left was refused: no chord was pressed and the text was untouched. Once that bind was removed, as a reload would, the driver bound the chord again and the keys worked. The next call reused that bind.

  • With fcitx5 stopped, the earlier run was also 47/47 and V1–V6.

  • Background delivery on 0.44: desktop text in the background arrives. A background key aimed at the focused window is refused (primary_target_busy), which is why the driver uses the foreground.

Tests

  • tst/unit/drivers/ passes, 81 tests. New Hyprland cases:
    • text goes to the desktop;
    • keys go to the window with the US-keyboard mapping;
    • Super goes to the desktop;
    • with nothing focused, keys go to the desktop with keysym names;
    • a grab refusal retries at the desktop;
    • any other refusal fails without a retry;
    • readiness checks the Hyprland pin, not the X11 one;
    • a key refused for the keymap is sent again after the reset chord, and the bind is made only once;
    • with no bind possible, or with the chord bound to something else (alone or beside ours), the refusal is raised and no chord is pressed;
    • after a reload empties the chord, the driver binds it again;
    • a key still refused after the chord fails in time.
  • ruff check is clean.

🤖 Generated with Claude Code

RetriggerView in GreptileConfidence Score: 5/5

The changes appear safe to merge; no new blocking issue was found.

Summary

Gives Hyprland its own cua-driver 0.44.0 pin, sends text to the desktop, and sends editing keys to the focused window.

  • Hyprland sends text to the desktop and ordinary keys to the focused window.
  • Refused window keys can reset the US keymap and retry.
  • Hyprland checks its own cua-driver build and tool list.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Window key refused] --> B{unsupported_layout?}
  B -->|No| C[Return refusal]
  B -->|Yes| D{Reset chord bindings}
  D -->|Only this driver's bind| E[Press reset chord]
  D -->|No bind| F[Create no-op bind]
  D -->|Any other bind| C
  F --> G{Exactly one bind listed?}
  G -->|Yes| E
  G -->|No| C
  E --> H[Retry window key for up to one second]
Loading

Reviews (7) · Last reviewed commit: "fix(drivers): press the keymap reset cho..." · Reviewed by Greptile

…w and text to the desktop

On Hyprland the driver runs cua-driver 0.44.0, its own pin: computer-ready checks that wheel's executable
(hyprland/amd64) and the tools mcp-hyprland.json pins, captured from 0.44.0's MCP server on Omarchy.

Text goes to the desktop in the foreground, where Hyprland's shortcuts, a menu holding the keyboard and non-ASCII text
work. A key goes to the focused window in the foreground, where Backspace, the arrows and Home/End edit text, pressed as
on a US keyboard (a shifted character as Shift and its key), the only layout the plugin takes there. Super and keys held
with it, a key with nothing focused, and one refused while a layer such as Omarchy's menu holds the keyboard go to the
desktop, punctuation by its keysym name.

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 07:19
…d changes it

Omarchy runs fcitx5, which takes on the keymap that cua-driver's desktop text uploads, after which cua-driver refuses
keys aimed at a window (unsupported_layout). The driver now presses Super+Ctrl+Alt+Shift+F12 at the desktop, a chord of
the US layout's own keys, which makes cua-driver upload that layout's keymap and fcitx5 take it on in turn, and which it
first binds to nothing in Hyprland so no window sees it; then it sends the key again.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…n bind has it

A bind someone else gave Super+Ctrl+Alt+Shift+F12 could do anything, so the driver now remembers the bind it made, as
Hyprland lists it (dispatcher and argument), and presses the chord only while that bind alone has it. With the chord
bound to anything else, the key fails as cua-driver refused it, with a hint saying why; with the chord unbound, as
after a config reload, the driver binds it again. The retry interval is named beside the wait.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@earakely-scale
earakely-scale merged commit e22691e into main Nov 9, 2026
35 checks passed
@earakely-scale
earakely-scale deleted the edgararakelyan/cua-driver-hyprland-key-routing branch November 9, 2026 17:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant