Keyboard
What a terminal can actually send, and the rules a keymap follows
A keymap has three parts: an action (next-space), the scope it is live in (workspace, code, …) and the chord you press (ctrl+o). Read this before rebinding: a key that never arrives looks exactly like a broken feature.
What a terminal can actually send
A terminal without an enhanced keyboard protocol has three ways to encode a
keystroke: a character, a control byte (Ctrl plus a letter), and an escape
sequence (function and navigation keys, and Alt as a prefix). Everything
else has no encoding at all.
Refused outright. Six control chords are other keys on a terminal, and uze will not let you bind them:
| You wrote | It is |
|---|---|
ctrl+i | Tab |
ctrl+m | Enter |
ctrl+j | line feed |
ctrl+h | Backspace |
ctrl+[ | Esc |
ctrl+space | NUL |
Universal. Ctrl+letter (except the above), F1–F12, Shift+F…, and
unmodified Enter/Esc/Tab/Shift+Tab/arrows/Page…/Home/End. These
reach uze over ssh, inside tmux, on WSL, anywhere.
Depends on your terminal. Alt+letter and Alt+digit are ESC-prefixed
and need the host to send Meta rather than compose a character: the default on
Linux, WSL and Windows Terminal, and off by default on macOS Terminal.app
and iTerm2, where Option composes accented characters. Also here: modified
navigation keys (ctrl+up, ctrl+pageup), which an emulator often claims
first for its own tabs.
Needs an enhanced protocol. Ctrl+digit, Ctrl+Shift+letter,
shift+enter, ctrl+enter. The protocol is requested at startup and used
when the terminal agrees (kitty, foot, WezTerm, ghostty, Alacritty, recent
iTerm2 and Windows Terminal). Where it does not, the Shortcuts screen says the
chord cannot be sent rather than binding it and leaving it dead.
On WSL specifically: a Linux uze under Windows Terminal reads VT bytes from
a pty (the Win32 console key API is not in the path), so it sees exactly what
any Linux terminal sees. Every universal chord works, Alt works, and
Ctrl+digit does not unless the protocol is on.
The answer that is actually true for your machine is the Shortcuts screen's capture: it is a probe. Press the key you are wondering about; it says what arrived. No table can enumerate every emulator × multiplexer × ssh × layout, and this one does not have to.
The rules the screen enforces
- A key means one thing per keyboard. uze has two: management, where it owns the whole keyboard, and the workspace, where every bare key belongs to the agent running in the pane. Within one of them, two actions may not share a mnemonic. Structural keys (Enter, Esc, Tab, the arrows) are contextual by nature and exempt: "go on" reads from the surface, and nobody is confused by it.
- A conflict is refused before it is written, and the screen says what the key already means.
- A file that cannot be used changes nothing. The keyboard already in force stays in force, and the problem is printed with the entry that caused it, since an operator without a keyboard cannot fix the file that took it away. An entry naming an action or a surface this build has never heard of is a warning: a keymap written for a newer uze still loads on an older one.
What a keymap deliberately cannot change
- What happens inside a pane. Keys uze does not claim are the agent's, and rebinding one takes it away from every agent you run.
- Mouse gestures. Every action bound outside a pane is reachable with the pointer, and that is the floor the keyboard sits on rather than a fallback for it.
- Chord sequences and modal states. One chord, one action. This is not vim and not tmux, and a prefix key is a course you have to take.
Windows Terminal keeps Ctrl+Shift+*, Alt+Enter, Ctrl+Tab and Ctrl+V
for itself, and under tmux or screen the multiplexer's own prefix wins first.
None of those ever reach uze, whatever you bind them to.