showmethekey: a screenkey alternative that reads the keyboard directly

The problem with the tool it replaces

The feature section explains the whole project in two paragraphs, and it starts with the tool this one is an alternative to.

screenkey is a popular project for streamers and tutorial recorders because it visualises your typing on screen. But it does not work with Wayland, because it uses X11 only functions to get keyboard events. That is the entire reason this project exists, and it is worth pausing on how sharp the problem is: the feature is the reason the tool is popular, and the feature is the thing that cannot be done on a modern desktop, because the mechanism it used to capture key events is part of the display server that Wayland replaced.

Show Me The Key reads key events via libinput directly, and then shows them on screen. The consequence, stated in the readme, is that it does not depend on X11 or on special Wayland compositors, and will work across them.

That last clause is the real design goal. A Wayland compositor is a moving target, and the applications that work on one and not another are a familiar complaint. Reading from the input stack rather than from the display server means the program sits below the compositor entirely, and the only thing that varies is where it draws.

The project came out of a SUSE Hack Week, and the link in the readme points at the project description, which frames it as a screenkey alternative that works under Wayland by reading the evdev device directly.

The licence is Apache 2.0, the site is showmethekey.alynx.one, and the release history is regular, with version 1.21.0 in March 2026 after two releases in the preceding weeks.

Reading the input stack rather than the display server

The project structure section explains the two parts, and the first of them is the more interesting one.

The command line part exists because of the security policy of Wayland, which means you cannot run a GUI program with sudo. The readme suggests splitting the program into a GUI frontend and a command line backend that does the privileged operations, and this is the backend: a custom rewrite of the debug events tool that ships with libinput, based on libinput, on the udev library, and on the evdev library.

So the architecture is: the input stack is talked to through libinput, the devices are enumerated through udev, and the raw events are read through evdev. The three libraries are the three layers of the Linux input system, and the project uses all three because the debug tool in libinput does.

The output format is JSON, one object per line, and the readme gives an example with the field names in it. There is an event name, an event type with its numeric code, a timestamp, a key name, a key code, a state name, and a state code. So the backend normalises the raw event into a flat record with a stable key name, which is what makes the output usable by something other than the tool that produced it.

The line format is deliberate, and it is the format that makes a pipeline easy: one JSON object per line is what a stream of records looks like, so a consumer can read it line by line without waiting for the stream to end, and the tool that consumes it here is the GTK frontend.

The GUI part is a frontend based on GTK, which runs the command line backend as root through the privilege escalation tool, and shows a transparent floating window to display the events.

Installing, in four distributions

The install section leads with the distribution package as the recommended route, and the four it covers are the four where a package exists today.

For AOSC OS it is a single package manager command, and for Arch Linux it is a single command as well. openSUSE is the more involved case: the packages live in a build service project, so the repository has to be added first and then the package installed, and there is a second package for the translations. The readme notes that users of the Leap release should swap the repository URL for their version rather than using the one for the rolling release.

Fedora is the case with the most variants, and it is worth reading closely. The simple route enables a personal build repository and installs the package. The route for an Atomic Desktop, which is the immutable Fedora variant that Silverblue, Kinoite, and Sericea are built on, is different: the release number goes into an environment variable, the repository file is written to the package directory with a download, and the installation goes through the image update tool rather than the package manager, because on an immutable system that is what installing a system package means.

That last difference is a nice illustration of how much the packaging story varies across distributions, and why a project that only documents the Fedora route would be documenting a minority of its users.

For everything else, the readme asks for help: please help package showmethekey to your distribution. That is a one-line request, and it is a common one in projects that have a small user base spread across many distributions.

Building from source

The source build is a meson project, and the dependency list is long enough to be informative on its own.

The input side needs libevdev, udev or systemd, and libinput. The display side needs GTK4, libadwaita, cairo, pango, and libxkbcommon. There is json-glib for the JSON output, and polkit for the privilege escalation. And the build tooling is meson with ninja and a C compiler.

What that list says is that this is a native GTK4 application with a modern desktop toolkit, using the Adwaita widget set, and that it takes the privilege question seriously enough to integrate with the system authorisation agent rather than asking for a password itself.

The build itself is four commands.

$ git clone https://github.com/AlynxZhou/showmethekey.git
$ cd showmethekey
$ mkdir build && cd build && meson setup --prefix=/usr . .. && meson compile && meson install
$ showmethekey-gtk

The separate build directory with the setup pointing at the parent is the standard out-of-tree meson pattern, and the prefix argument is what makes the install land in the right place for a distribution package rather than in a local directory.

The last command in that block is the one to notice, because there is more than one executable. The graphical front end is launched as showmethekey-gtk, and the readme's project structure section makes clear that the command line backend is a separate program with a separate name. The repository layout matches: a directory for the command line part, a directory for the GTK part, a shared directory for the code both use, a meson build file at the root, a build options file, and a post-install script written in Python.

The permission model, and what the program does not do

The usage section is where the security model is described, and it is worth reading precisely because this program watches the keyboard.

To read keyboard events, the program needs superuser permission, and the readme says you may need to input an admin password if there is a polkit authentication agent's dialog, because the program needs superuser permission to read keyboard events, and then adds the parenthetical that this program does not handle your password. That last clause is the important one: the password is typed into the system's own authorisation dialog, not into the application, so the application never sees it. The authorisation agent belongs to the desktop, and it is the thing that asks.

The second sentence is a practical detail for people who already have the right group membership: users in the wheel group can skip password authentication. So the privilege requirement can be satisfied by group membership rather than by a prompt, which is the arrangement a system administrator would set up for a machine with several people using it.

The other half of the permission model is architectural, and it is the reason for the split described earlier. On Wayland you cannot run a GUI program as root at all, so the privileged work is in a command line backend, and the graphical part is an ordinary unprivileged program that starts the backend through the escalation tool. The reading of the keyboard happens in a process the user can see being started, and the window drawing happens in a process that has no special rights.

The readme also documents the behaviour of the window itself. There is a switch to show the floating keys window, and a clickable switch that can be disabled, at which point the window becomes click-through, so it does not swallow the clicks meant for the application underneath. The switch is described as something you may disable once you have configured your compositor to pin the window at the top, and it can also be toggled at run time by pressing the control key twice quickly, with the same trick for the alt key toggling a pause.

The one thing Wayland will not let a client do

The special notice for Wayland session users is the most technically interesting section of the readme, and it explains a limitation that no amount of clever programming can work around.

There is no official Wayland protocol allowing toplevel clients to set their own position and layer; only users can change those things. The readme then does the useful thing and explains the way out: users are always allowed to do those things by themselves if their compositor supports it.

So the design of this program is constrained by the desktop, not by the programmer. The keys window floats, and the user drags it wherever they want, and if the compositor offers a way to keep a window on top or on every workspace, the user can use that.

The readme then gives the per-desktop recipe, which is the practical part. On GNOME Shell you right click the clickable area in the title bar to get the window manager menu, and there are entries for always on top and always on visible workspace. On KDE Plasma it is the task bar entry, with a move to desktop option set to all desktops and a keep above others action. For Sway it is a configuration snippet.

for_window [app_id="showmethekey-gtk" title="Floating Window - Show Me The Key"] {
  floating enable
  sticky enable
}

For Hyprland there are two variants, one for the Lua configuration and one for the Hyprlang configuration, because the format of the configuration file changed in a recent version, and the readme notes that the older path still works.

windowrulev2 = float,class:^(one.alynx.showmethekey)$
windowrulev2 = float,class:^(showmethekey-gtk)$ # make window floating
windowrulev2 = pin,class:^(showmethekey-gtk)$ # pin window

The comments in that snippet carry a piece of advice that is worth having: the clients command in the compositor shows the class, the title, the XWayland status, and the size of a window, and you need those to write a rule that matches. The two class names in the rules are the two ways the application identifies itself, the desktop entry style identifier and the plain executable name, and both are given because which one a rule matches depends on how the window was launched.

Finally there is a section for people who are tired of the settings window, which explains the command line options: a flag to show the keys window by default, a flag to hide the application window by default, and a flag to make the keys window click-through by default for people whose compositor rules already place it.

Editorial conclusion

showmethekey fits a person recording a tutorial or streaming who wants the keystrokes visible on screen and who is on a Wayland session, where the older tool does not run. It does not fit a user on X11 who is happy with what screenkey already does, and it does not fit somebody who would rather not grant a program read access to the keyboard at all. Verify first that your compositor allows the floating window to be placed where you want it, because no Wayland protocol lets a client position itself and the configuration is per desktop, that you understand the privilege model before you start it, since the backend runs as root through the authentication agent, and that the group your user belongs to determines whether you are asked for a password at all.

Frequently asked questions

Official sources

1. AlynxZhou/showmethekey on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases