On-screen overlay of currently pressed keys, for screen recordings.
The overlay is a click-through box of keycaps. It defaults to the bottom center, without an outer box. Position, padding, scale, outer box, corner rounding, colors, and an optional shortcut action label are configurable.
Demo - held keys on the overlay (Super+Enter opens a terminal), then the settings panel: shortcut action, mouse labels beside the chord, position and custom scale, a color theme, and a click ripple.
Overlay - currently held keys as keycaps, with the Hyprland bind description underneath. Super+W shows Close window, the same text Super+K lists for that shortcut. The box is click-through so it does not steal clicks in a recording.
The center layout is a wide box in the middle of the screen. The box stays one size on every tab.
Center layout, Overlay page. Side, Center, and Fullscreen switch the layout. Pressed keys, typed characters, preview, and the outer box sit in the left column. Rounding, font, linger, and the shortcut action sit in the right.
Center layout, Position page. Monitor, vertical, horizontal, and edge padding sit in one row. Scale stays on its own line.
Center layout, Colors page. Theme chips wrap across the box. Background, border, and font each have a header and a hex field.
Center layout, Mouse page. Show mouse, placement, and labels sit beside the button, scroll, and ripple columns. Follow rate and ripple size share a line.
Center layout, Ignore page. Record a chord, then select it and remove it, or remove all.
The side layout is the narrow panel beside the bar.
Side layout, Overlay page. Turn the overlay on, optionally preview a sample hotkey while this panel is open, set outer box, rounding, and a searchable system font, linger after release, and place the shortcut action above or below the keys. The Hyprland bridge is installed or removed from this page.
Side layout, Position page. Vertical and horizontal edge (including middle), padding from the chosen edge, and overlay scale. Custom sits on the same row as the presets and opens a spin field for 0.5-5.
Side layout, Colors page. Every palette is a chip: Shell follows the Omarchy theme and fills background, border, and font with the colors in use. Neon, Matrix, Vapor, and the other presets fill those hex fields too. Editing a hex value switches to Custom.
- Shows the keys that are currently held, not a typing history
- Optional typed characters: Shift+1 shows
!from the active keyboard layout. Super, Ctrl, and left Alt chords stay as key names. Always show uppercase turns those letters intoAwhile symbols stay as typed - Default position: bottom middle
- Configurable vertical edge (
top/middle/bottom) - Configurable horizontal edge (
left/middle/right) - Optional monitor: every screen, the focused monitor, or one specific connector. The default is every screen
- Configurable padding from the chosen edge (0-400 px, default 24; ignored on a middle axis)
- Optional outer box around the keycaps
- Optional corner rounding (0-32 px, default 8)
- Overlay scale (
1x/1.25x/1.5x/1.75x/2x/ custom 0.5-5) - Overlay font: Shell (Omarchy UI font) or any family installed on the system
- Mouse clicks and scroll on their own settings page: which buttons, placement, linger, and an optional cursor ripple. Follow a drag can slide that ripple while the button is held. Fade out lowers its opacity across the ripple linger. Short labels are
LMBandWheel Dn. Full names areLeft mouseandScroll down, so they do not match the arrow keys (Left arrow,Right arrow,Up arrow,Down arrow) - Optional shortcut action from Hyprland bind descriptions (same source as Super+K)
- Action placement above or below the keycaps
- Color themes (Shell, Dark, Light, Contrast, Nord, Mocha, Gold, Neon, Matrix, Vapor, Cyber, Ember, Ice) plus custom hex for background, border, and font
- Settings panel can show a live overlay preview of a random real hotkey while open
- Short linger after release (default 600 ms) so quick taps stay visible on video
- Optional show while recording: the overlay follows Omarchy's screen recorder (
gpu-screen-recorder). It turns off when the take ends only if Keycast turned it on. A manual overlay stays as you left it - Left-click the bar icon to toggle the overlay
- Right-click the bar icon for Overlay, Position, Colors, Mouse, Ignore, and the Hyprland bridge
- Ignore tab: record a chord by holding it for half a second. That exact combination stays off the overlay. Select one in the list and remove it, or remove all
- Settings layout: Side is the panel beside the bar. Center is a wide box in the middle of the screen. Fullscreen fills the screen around the bar, and each page spreads into that space
- IPC:
omarchy-shell keycast toggle(alsoshow,hide,state).omarchy-shell keycast settingsopens or closes the settings panel
Keycast is an on-screen display for recordings, not a logger.
- No
/dev/inputor evdev listener - No key history, timestamps, or log files
- Held keycodes live only in Hyprland/Quickshell memory
- Ignored chords are combinations you record on purpose. They are saved with the other settings, not as a key log
- The overlay is off until you turn it on
- Disable or remove the Hyprland bridge when you are not recording if you want the observer unloaded
git clone https://github.com/kenwi/keycast.git ~/Work/keycast
ln -s ~/Work/keycast ~/.config/omarchy/plugins/keycast
omarchy plugin enable keycastRight-click the keyboard icon on the bar and choose Enable Hyprland bridge.
That appends a three-line block to ~/.config/hypr/hyprland.lua and reloads
Hyprland. Left-click the icon to show the overlay, then hold keys to preview it.
Saved plugin files reload automatically. If the plugin is a symlink, prefer
omarchy restart shell after edits so QML definitely reloads.
Add a bind in ~/.config/hypr/bindings.lua so you can show or hide the overlay
without clicking the bar. Super+K already opens the keybindings list; Super+Shift+K
is free in Omarchy defaults and stays next to that:
o.bind("SUPER + SHIFT + K", "Toggle keycast", "omarchy-shell keycast toggle")
o.bind("SUPER + SHIFT + L", "Keycast settings", "omarchy-shell keycast settings")Reload Hyprland after saving. The description appears in Super+K. Pick any unused combo if you already bound that one. One-way variants for the overlay:
o.bind("SUPER + SHIFT + K", "Show keycast", "omarchy-shell keycast show")
o.bind("SUPER + SHIFT + J", "Hide keycast", "omarchy-shell keycast hide")Persisted on the bar entry in ~/.config/omarchy/shell.json:
{
"id": "keycast",
"overlayEnabled": false,
"showWhileRecording": false,
"showTyped": false,
"showUppercase": false,
"frameEnabled": false,
"roundingEnabled": true,
"rounding": 8,
"vertical": "bottom",
"horizontal": "middle",
"overlayMonitor": "all",
"overlayMonitorName": "",
"settingsLayout": "side",
"ignoredChords": "",
"padding": 24,
"scale": 1,
"scaleCustom": false,
"lingerMs": 600,
"actionEnabled": true,
"previewEnabled": true,
"actionPosition": "above",
"fontFamily": "shell",
"colorTheme": "shell",
"backgroundColor": "#1A1A1A",
"borderColor": "#6E6E6E",
"fontColor": "#F5F5F5",
"mouseEnabled": true,
"mousePlacement": "inline",
"mouseLabelStyle": "short",
"mouseLingerMs": 500,
"mouseRipple": true,
"mouseRippleSize": 36,
"mouseRippleMs": 400
}| Key | Values | Default |
|---|---|---|
overlayEnabled |
true / false |
false |
showWhileRecording |
true / false |
false |
showTyped |
true / false |
false |
showUppercase |
true / false |
false |
frameEnabled |
true / false |
false |
roundingEnabled |
true / false |
true |
rounding |
0-32 px | 8 |
vertical |
top / middle / bottom |
bottom |
horizontal |
left / middle / right |
middle |
overlayMonitor |
all / focused / specific |
all |
overlayMonitorName |
Hyprland connector, such as DP-1 |
empty |
settingsLayout |
side / center / fullscreen |
side |
ignoredChords |
comma-separated keycode chords, such as 38+133 |
empty |
padding |
0-400 px | 24 (ignored on a middle axis) |
scale |
1 / 1.25 / 1.5 / 1.75 / 2, or 0.5-5 when custom |
1 |
scaleCustom |
true / false |
false |
lingerMs |
0-2000 ms | 600 |
actionEnabled |
true / false |
true |
previewEnabled |
true / false |
true |
actionPosition |
above / below |
above |
fontFamily |
shell or an installed family name |
shell |
colorTheme |
shell / dark / light / contrast / nord / mocha / gold / neon / matrix / vapor / cyber / ember / ice / custom |
shell |
backgroundColor |
#RRGGBB |
#1A1A1A |
borderColor |
#RRGGBB |
#6E6E6E |
fontColor |
#RRGGBB |
#F5F5F5 |
mouseEnabled |
true / false |
true |
mouseLeft / mouseRight / mouseMiddle |
true / false |
true |
mouseBack / mouseForward |
true / false |
false |
mouseWheelUp / mouseWheelDown |
true / false |
true |
mouseWheelLeft / mouseWheelRight |
true / false |
false |
mouseRequireKeys |
true / false |
false |
mouseRipple |
true / false |
true |
mouseRippleScroll |
true / false |
false |
mouseRippleFollow |
true / false |
false |
mouseRippleFollowMs |
8-64 ms | 16 |
mouseRippleFade |
true / false |
false |
mousePlacement |
inline / above / below |
inline |
mouseLabelStyle |
short (LMB) / name (Left mouse) |
short |
mouseLingerMs |
0-2000 ms | 500 |
mouseRippleSize |
8-160 px | 36 |
mouseRippleMs |
100-2000 ms after release | 400 |
CLI examples:
omarchy bar set keycast vertical middle
omarchy bar set keycast horizontal middle
omarchy bar set keycast padding 40
omarchy bar set keycast scale 1.25
omarchy bar set keycast scaleCustom true
omarchy bar set keycast scale 1.4
omarchy bar set keycast frameEnabled false
omarchy bar set keycast roundingEnabled false
omarchy bar set keycast rounding 12
omarchy bar set keycast actionEnabled true
omarchy bar set keycast previewEnabled false
omarchy bar set keycast actionPosition above
omarchy bar set keycast fontFamily "JetBrainsMono Nerd Font"
omarchy bar set keycast colorTheme mocha
omarchy bar set keycast backgroundColor "#1A1A1A"
omarchy bar set keycast borderColor "#6E6E6E"
omarchy bar set keycast fontColor "#F5F5F5"
omarchy-shell keycast toggle| File | Role |
|---|---|
manifest.json |
Plugin id, service + bar-widget entry points, settings schema |
Service.qml |
Bridge events, overlay state, IPC, settings |
Overlay.qml |
Click-through corner box on the chosen monitors |
KeycastCard.qml |
Keycap card drawn by the overlay |
BarWidget.qml |
Toggle + settings panel host |
Panel.qml |
Side panel and centered wide panel |
SettingsForm.qml |
Overlay, position, colors, and mouse controls |
WidePanel.qml |
Centered settings window |
Keys.js |
Keycode labels, typed characters, protocol parse, bind catalog, settings normalize |
scripts/typed-chars |
Active layout characters for the typed overlay |
bridge.lua |
Hyprland keyboard observer and non-consuming mouse binds |
scripts/bridge-control |
Inspect / enable / disable the managed Hyprland block |
screenshots/ |
Demo GIF, side settings pages, and center layout pages for this README |
README.md |
This file |
keycast/tests/run