Hold a modifier, see what it does. bindpeek reads the shortcuts your compositor is actually configured with and shows them while you hold the keys, without taking the keyboard away from you.
bindpeek-demo-standbilder.mp4
The panel in all five positions and all fourteen palettes, with one and two modifiers held, and the plate fading out from under the text at the end.
Nobody remembers every combination they once bound. The usual answer is to open the configuration file in a second window and read it, which is the one thing you cannot do while holding the keys you are asking about. bindpeek puts the list on screen instead, for exactly as long as the modifier is down, and the shortcut still fires when you complete it.
Features:
- Reads the shortcuts of the running session: mango, Hyprland, sway and KDE Plasma, each from the file or service that session really uses
- Appears while a modifier is held and goes when it is released, after a delay you set
- Never takes the focus and never eats a key: the panel is a bystander, so the combination you are looking at still works
- Narrows the list as you add modifiers, and shows what a further modifier would reach in one of four ways
- Reads the source again before every appearance, so an edited configuration is live without restarting anything
- Fourteen palettes, or follow the desktop's light/dark setting; position, distances, font, corners, border and transparency all settable
- A settings window with a live preview of the real panel, and a tray icon that switches the panel on and off
- Prints the same list as plain text in the terminal:
bindpeek --list - German and English
Note
The panel is a wlr-layer-shell surface, which is what lets it float above
everything without taking the focus. Every wlroots-based compositor carries
that protocol, and so do Hyprland, KWin and niri, but not GNOME/Mutter,
not Cinnamon, whose compositor is a fork of Mutter, and not X11. On a session
without it, bindpeek says so and stops instead of
coming up as an ordinary window. --list works anywhere.
git clone https://github.com/Maik-0000FF/bindpeek.git
cd bindpeek
./install.shThe script names what is missing before it installs anything, builds, and then
asks two questions separately, because both change more than an installation
normally does: whether to switch on the service that reads the keyboard, and
whether to start the tray with your session. It also offers to take away the
input group if an earlier version put your account in it, because nothing
here needs it any more.
# flake inputs
bindpeek.url = "github:Maik-0000FF/bindpeek";
# NixOS configuration
imports = [ inputs.bindpeek.nixosModules.default ];
programs.bindpeek = {
enable = true;
# Off by default, because it starts a program in everybody's session:
autoStart = true; # tray in every graphical session
};autoStart writes the desktop entry into /etc/xdg/autostart, which only a
desktop environment reads. Under a compositor started from a script, put a line
in its own startup file instead:
bindpeek-editor &Start the tray icon and the settings window:
bindpeek-editorThe panel comes up with it. Hold a modifier, and the shortcuts that modifier fires appear. Add a second modifier and the list narrows to what the two of them fire together. Release, and it is gone.
The same list as text in the terminal:
bindpeek --listThis is also the quickest way to see what bindpeek reads out of your configuration, and it is what still works on a session that cannot show the panel.
Other options:
| Option | What it does |
|---|---|
--list |
Print the shortcuts instead of showing the panel |
--keys |
Print the held modifiers as they change, to check that the event devices can be read |
--environment mango|hyprland|sway|kde |
Force the session instead of detecting it |
--source <path> |
Read the shortcuts from this file instead of the session's own |
--help, --version |
The usual |
bindpeek-editor and bindpeek-watch take no options of their own.
bindpeek-editor answers --help and --version through the same parser as
the panel, so --help-all and a run like -hv are answered as well.
bindpeek-watch carries no Qt and answers exactly --help, -h, --version
and -v.
Everything else is set in the settings window, or by editing
~/.config/bindpeek/bindpeek.conf, which the program writes on first start with
a comment above every line. Both are read live. See
Configuration.
- A Wayland session whose compositor implements
wlr-layer-shell. Every wlroots-based one does, which is mango, sway, river and their like, and so do Hyprland, KWin and niri, which are each built on something of their own and carry the protocol anyway. GNOME/Mutter and X11 cannot show the panel. - systemd. The keyboard is read by a service that the socket unit starts when the panel connects, and that runs under an account the service manager makes and unmakes around it. The panel appears while a modifier is held, and a Wayland program is told nothing about a key until it has the focus, which the panel deliberately never takes; so the modifiers are read below the compositor, and this is what keeps that ability out of your account. See How It Works.
- Qt 6.7 or newer, layer-shell-qt, libevdev and libsystemd.
install.shinstalls them for you, and shows every package by name before it does. What that comes to on your distribution: What gets installed. - A release recent enough to carry that Qt. On the Debian side that means Ubuntu 26.04 or newer and Debian trixie or newer; the automated checks build and install on Arch, Ubuntu 26.04, Fedora and openSUSE Tumbleweed on every push. Older releases are not held back on purpose, they simply carry a Qt this was not written against.
- For the KDE backend only, KDE's KConfig framework. The build looks for it and says what it found: where there is none, that one backend is left out and nothing else is affected, and a machine without the framework has no KDE Plasma 6 whose shortcuts there would be to read.
Reading the shortcuts themselves is a second question, and there the answer is narrower: mango, Hyprland, sway or KDE Plasma. On any other compositor the panel can be drawn but there is nothing yet to fill it with, and bindpeek says which session it found rather than guessing.
./uninstall.shIt removes the programs, the desktop entry and its icon, and asks before it touches your settings. The packages it installed to build with are left alone.
Something not working, or a session you would like supported? Open an issue with
the output of bindpeek --list and your compositor's configuration, and it will
be looked at.
Building it yourself is in Installation.
scripts/check.sh runs every check that can run on one machine. On every push,
that same script runs again with the flake, alongside a build and the suite in a
container of five distributions, six runs in all because one of them is built
twice with different compilers, the install and uninstall pair in four of them
and once more with every question answered, and the suite again under the
address and behaviour sanitizers.
If you find bindpeek useful, you can support its development:
聽
A star also helps, it makes this project easier to discover.
GPL-3.0-or-later. See LICENSE.
Maik-0000FF