TUI Keybinding Debug

When to Use This Skill

The Core Insight

When a TUI key "does nothing," the instinct is to debug the app — its keymap, event matching, focus model. That instinct is wrong about half the time. A keystroke passes through three layers before the app can match it, and it can die silently at any of them:

1. Terminal interception — the terminal (kitty, WezTerm, Ghostty, foot) consumes its own configured shortcut before the program sees the byte. No bytes reach the app, so no app-side config or code can catch it.
2. Layout-impossible chord — on a non-US layout the character itself needs a modifier, so the Ctrl-combo is unproducible. The terminal never emits it; there is nothing to intercept.
3. App-side legacy aliasing — the key does reach the app, but legacy terminal encoding aliases distinct keys to the same byte (Ctrl+J == Enter), so the binding fires the wrong action.

Diagnose the layer first. One debug run settles where the key dies in seconds, converting an open-ended app-side hunt into a targeted fix. Prefer a key the terminal forwards: bare Ctrl+<letter> is the only Ctrl-space that exists on every keyboard layout and passes through every terminal.

Execution

Diagnose this dead-keybinding failure by proving which of the three layers is eating the key. Work top-down — cheapest, most-common cause first.

Step 1: Prove where the key dies (terminal vs app)

Run these two kitty probes and press the dead key. (Adapt for other terminals — most have a key-debug mode; the reasoning is identical.)

kitty +kitten show_key -m kitty

Press the dead key. Nothing printed = the terminal ate it (layer 1 or 2). A clean CSI ... u / escape sequence printed = the key is reaching the app, so the bug is app-side (jump to Step 4).

kitty --debug-keyboard

Press the dead key and read the log. The smoking gun is a line like:

KeyPress matched action: <X>, handled as shortcut

handled as shortcut means the terminal claimed the key — confirm layer 1 and go to Step 2. If show_key printed nothing and the chord involves a shifted/AltGr character on your layout, suspect layer 2 (Step 3) before the terminal.

Step 2: Layer 1 — terminal interception

The terminal grabbed the key. Identify whether it's a user-config map (changeable) or a built-in default (usually not). Grep the kitty config for a map on the offending key:

grep -niE '^\s*map\s+' ~/.config/kitty/kitty.conf

Match the dead chord against this table of commonly-intercepted combos:

Fix, in order of preference:

1. Rebind the app to a key the terminal forwards — a bare Ctrl+<letter> the app doesn't already use (e.g. switch_mode = ["Ctrl+T"]). This is the robust fix: it dodges interception everywhere.
2. Free the key in the terminal — only if it's a user map: map shift+down no_op in kitty.conf. A built-in default (like Ctrl+Shift+Arrow scrollback) usually can't be freed cleanly without overriding it.

Distinguishing default from user config matters: a user map is changeable; a built-in default is not (without an override that may cost you the terminal feature).

Canonical break (jnv on kitty): the JSON-viewer nav keys looked completely dead. Root cause was not jnv — kitty intercepted shift+down/shift+up (mapped to move_window in the user's kitty.conf), so jnv's switch_mode focus-switch never fired. Two replacement guesses also collided: ctrl+shift+arrow is a kitty built-in scrollback default. The fix was bare Ctrl+T — a key kitty forwards.

Step 3: Layer 2 — layout-impossible chord

On non-US layouts the character itself needs a modifier, so a Ctrl-combo over it can never be typed — the terminal never emits it, and nothing intercepts it, it simply doesn't exist. The failure is extra-invisible because a header hint (^/ preview) reads as a truncated or garbled label rather than an impossible chord.

Finnish / Nordic ISO layout examples — each of these requires Shift/AltGr, so the bare Ctrl-combo is unproducible:

Rule of thumb: punctuation Ctrl-combos (ctrl-/, ctrl-?, ctrl-\, ctrl-], ctrl-; …) are layout-dependent — treat them as unavailable when authoring binds meant to work across keyboards. The diagnosis is the same show_key run: if pressing the chord prints nothing and the character is shifted/AltGr on your layout, the layout is the culprit, not the terminal.

Fix: rebind to a bare Ctrl+<letter> — the only Ctrl-space that exists on every layout and passes through every terminal.

Canonical break (dotfiles): every gh fzf picker bound ctrl-/:toggle-preview; on a Finnish layout the preview toggle was dead in all of them because the keyboard has no bare / key. Fix: rebind to bare Ctrl+T.

Step 4: Layer 3 — app-side legacy key aliasing (crossterm)

The key reached the app (Step 1's show_key printed a sequence), but legacy terminal encoding aliases distinct keys to the same byte, so a binding fires the wrong action or is unreachable:

Fix — negotiate the keyboard enhancement protocol so these disambiguate. Push KeyboardEnhancementFlags::DISAMBIGUATE_ESCAPE_CODES when supports_keyboard_enhancement() is true, and pop it on teardown:

use crossterm::event::{
    KeyboardEnhancementFlags, PushKeyboardEnhancementFlags, PopKeyboardEnhancementFlags,
};
use crossterm::terminal::supports_keyboard_enhancement;

if supports_keyboard_enhancement().unwrap_or(false) {
    execute!(stdout, PushKeyboardEnhancementFlags(
        KeyboardEnhancementFlags::DISAMBIGUATE_ESCAPE_CODES,
    ))?;
}
// ... run the app ...
execute!(stdout, PopKeyboardEnhancementFlags)?; // on teardown

Caveat — normalize events first, or the protocol breaks exact matches. If the app matches keybinds by exact Event equality, enabling the protocol also makes release/repeat events and KeyEventState lock-bits (Caps/Num Lock) possible — both break exact matches. At the single event-read chokepoint:

1. Drop non-Press events (ignore release/repeat).
2. Strip KeyEventState to NONE.
3. Request only DISAMBIGUATE_ESCAPE_CODES — not REPORT_EVENT_TYPES — to keep the stream close to legacy.

Agentic Optimizations

Quick Reference

Related

• kitty-session-persistence — kitty session snapshot/restore (sibling kitty skill)
• The user-global kitty-agent-interaction.md rule — the read-only kitty remote-control surface; this skill is its keyboard-interception debugging complement.