Showkeys Overlay

Showkeys draws the keys you press in the bottom-right corner of the screen. Viewers of a screencast or a live demo can see which shortcuts you used.

Turn it on

At startup, with the --show-keys flag:

tuios --show-keys
tuios new demo --show-keys
tuios attach demo --show-keys
tuios tape play demo.tape --show-keys
tuios ssh --show-keys
tuios-web --show-keys

While TUIOS runs, toggle it in any of three ways:

• Ctrl+B D k (the debug prefix)
• Toggle show keys in the command palette
• Show keys on the settings page

A toggle is saved to your config file, so the choice survives a restart. You can also set it by hand:

[debug]
show_key_events = true

Showkeys belongs to each client. Two clients attached to the same session each have their own setting and only show their own keys.

What it shows

Each key is drawn as a pill. Up to 5 keys are on screen at once:

 Ctrl + b   t   j ×3   Esc 

• Modifiers come before the key: Ctrl + c, Alt + 1, Ctrl+Alt + t.
• Shift is hidden on single letters, since the capital letter already shows it. Shift still shows on other keys, as in Shift + Tab.
• Repeats collapse. Pressing the same key again adds a count, as in j ×3, instead of a new pill.
• Special keys have short names: Enter, Esc, Tab, Space, Backspace, Delete, Home, End, PgUp, PgDn, and arrows as ↑ ↓ ← →.
• The leader key is highlighted in cyan, so the prefix stands out in a recording.
• Keys expire. Each pill disappears 3 seconds after its last press, and when a sixth key arrives the oldest one is dropped.

The overlay sits above the dock when the dock is at the bottom, and draws over windows and notifications. On a narrow screen it drops the oldest pills until the rest fit. The pill colors are fixed and do not follow the theme.

Showkeys shows keys, not what they do. It captures every key in both window management mode and terminal mode, before any binding handles it.

Recording a demo

1. Start TUIOS with showkeys and a theme that suits the recording:

   tuios --show-keys --theme nord

2. Start your screen recorder. A terminal recorder such as asciinema records the overlay along with everything else, because the overlay is part of what TUIOS draws.

3. Run your demo. Viewers see each shortcut in the corner as you press it.

For a demo you want to replay the same way every time, script it as a tape and play it with tuios tape play demo.tape --show-keys. Keys a tape sends go straight to the pane and do not appear in the overlay, so showkeys is most useful when you drive TUIOS by hand.

For a live talk, create the session ahead of time and attach when you start:

tuios new workshop --detach
tuios attach workshop --show-keys

Troubleshooting

Nothing appears. Check that showkeys is on. The toggle shows a notification with the new state. Keys vanish 3 seconds after they are pressed, so the overlay is empty while you are not typing.

A modifier is missing. Some terminals do not report every combination. Ctrl+Shift+letter often arrives as Ctrl+letter. A terminal with the kitty keyboard protocol, such as kitty, WezTerm, Ghostty or foot, reports more of them.

The overlay covers output. It sits in the bottom-right corner, over whatever is there. Toggle it off for a moment, or stop typing for 3 seconds and it clears.

Related