Repository navigation
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 intoNov 9, 2026
Conversation
…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>
…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
deleted the
edgararakelyan/cua-driver-hyprland-key-routing
branch
November 9, 2026 17:30
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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-readychecks 0.44.0's wheel executable (EXECUTABLES["hyprland/amd64"]) and the tools inmcp-hyprland.json. That manifest was captured from 0.44.0'scua-driver mcpon Omarchy: the same 66 tools, instructions and 11 resources as 0.38, but different schemas forclick,set_config,start_recordingandtype_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 typesAasa.Falls back to the desktop for:
foreground_grabbecause 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
supportsentry, 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 devicesthen reportsactive_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:SUPER + CTRL + ALT + SHIFT + F12bound to nothing, binding it throughhyprctl eval 'hl.bind(...)'if not;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 (
__luaand 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: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:
fcitx5-remote -s keyboard-us,-r,-c/-o,-t; D-BusReloadAddonConfig waylandimandSetCurrentIMomarchy-fcitx5.servicetext_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-plugin0.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: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:ruff checkis clean.🤖 Generated with Claude Code


Confidence 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.
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]Reviews (7) · Last reviewed commit: "fix(drivers): press the keymap reset cho..." · Reviewed by Greptile