hypr-xwayland-eavesdrop

A Hyprland plugin that forwards physical left Alt key events to XWayland while a native Wayland surface has keyboard focus. It is intended for XWayland applications such as Discord that need a real Alt_L push-to-talk binding.

The initial policy is intentionally narrow:

• Forward only physical KEY_LEFTALT.
• Never consume the focused application's normal Alt events.
• Ignore virtual, disabled, disallowed, and non-state-sharing keyboards.
• Stop forwarding and release background-forwarded keys while the session is locked.
• Release background-forwarded keys before focus enters XWayland, on plugin unload, and when policy cleanup is required.
• Clear stale state without writing to a destroyed XWayland client after an XWayland restart.

This plugin uses a Hyprland internal function hook and direct Wayland keyboard resource access. Rebuild it against the installed Hyprland headers after every Hyprland update.

Build

Dependencies:

• Hyprland development headers matching the running compositor
• CMake 3.19 or newer
• A C++23 compiler
• pkg-config

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build
ctest --test-dir build --output-on-failure

The plugin is produced at:

build/hypr-xwayland-eavesdrop.so

Install with hyprpm

The repository must be reachable through a Git URL for normal hyprpm add usage:

hyprpm add <repository-url>
hyprpm enable hypr-xwayland-eavesdrop
hyprpm reload

For local testing, load the built plugin directly:

hyprctl plugin load "$(pwd)/build/hypr-xwayland-eavesdrop.so"

Unload it with:

hyprctl plugin unload "$(pwd)/build/hypr-xwayland-eavesdrop.so"

Manual verification

Use an X11 key event viewer and Discord alongside a native Wayland application. Verify at minimum:

1. Left Alt press and release reach XWayland while Wayland is focused.
2. Wayland Alt shortcuts still work normally.
3. Alt is not duplicated while any XWayland application is focused.
4. Holding Alt across a Wayland-to-XWayland focus change does not stick.
5. Locking the session and unloading the plugin while Alt is held both release Alt in XWayland.
6. Two physical keyboards do not release XWayland Alt until both release it.

Watch the Hyprland log for messages prefixed with [xwayland-eavesdrop].