Keywisp

A small Wayland keystroke visualizer.

test.mp4

Dependencies

• Zig 0.17.0 (for 0.16.0, see tag 0.3.0)
• a Wayland compositor with wlr-layer-shell-unstable-v1.

System dependencies:

• cairo
• libinput
• pango
• udev
• wayland
• xkbcommon

Build-only dependency:

• wayland-protocols — needed to generate the xdg-shell, viewporter, and fractional-scale-v1 protocol bindings at build time, not required at runtime.

Install

Arch Linux (AUR)

yay -S keywisp-git

Build from source

zig build -Doptimize=ReleaseSafe --prefix ~/.local

This installs Keywisp as ~/.local/bin/keywisp. Make sure ~/.local/bin is in your PATH.

Input permissions

Keywisp needs read access to the input devices on seat0. On systems using an input group, add your user to it and then log out and back in:

sudo usermod -aG input "$USER"

Usage

Start the overlay with:

keywisp

Pointer buttons and scroll events are optional. Enable them with -B and -S:

keywisp -B -S

Keywisp includes four themes:

Theme	Appearance
dark	Dark panel (default)
light	Light panel
wisp-dark	Floating dark keycaps with soft shadows
wisp-light	Floating light keycaps with soft shadows

Select a theme with, for example:

keywisp --theme wisp-dark

Command-line options can override theme colors and adjust the position, font, spacing, and other appearance settings.

Example:

keywisp --theme wisp-light \
  --position top-right \
  --margin 32 \
  --max-width 720 \
  --font "Serif Bold 12"

Run the following command for all available options:

keywisp --help

Pause and resume

Enable signal control with -c / --signal-control:

keywisp -c

From another terminal or a WM script:

pkill -USR1 -x keywisp  # pause and clear the display
pkill -USR2 -x keywisp  # resume

These commands affect all matching instances; use kill -USR1 PID / kill -USR2 PID to target one. Without -c, these signals normally terminate Keywisp. If both are pending, pause takes priority.

See the polkit examples for niri, Hyprland, and Sway scripts that pause while an authentication window is focused and resume when focus leaves it.

Waybar integration

Keywisp can run in --stdout mode and be used as a Waybar custom module. Each keystroke line is printed to stdout and picked up by the bar. An example configuration is provided in examples/waybar-config.jsonc:

"custom/keywisp": {
  "exec": "keywisp --stdout --stdout-history 5 --stdout-emit-clear -t 2000",
  "format": "󰌌  {}",
  "hide-empty-text": true,
  "restart-interval": 3,
  "tooltip": false
}

Acknowledgments

Keywisp was inspired by DreamMaoMao/wshowkeys.

License

Keywisp is available under the MIT License.