Keywisp

A small Wayland keystroke visualizer.

test.mp4

Dependencies

• Zig 0.16.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

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.