# Showkeys Overlay

URL: https://tuios.dev/docs/showkeys

> Show the keys you press on screen, for demos, screencasts and teaching.

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:

```bash
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](https://tuios.dev/docs/configuration#the-in-app-settings-page)

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

```toml
[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.

> **It shows everything you type**
>
> Showkeys draws every key, including a password typed into a pane. There is no filter. Toggle it off with Ctrl+B D k before you type a secret, and back on after.

## Recording a demo

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

   ```bash
   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](https://tuios.dev/docs/tape-scripting) 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:

```bash
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

*[An interactive figure goes here. Open the page to use it.](https://tuios.dev/docs/showkeys)*