CSI u fixterms Key Encoding
A proposal for terminals to send every key, with any of Shift, Alt and Control, as one sequence no other key sends, by extending the encodings they already use.
CSI code ; modifiers u
CSI ~ Special Key
CSI number ; modifiers ~
CSI 1 ; m Cursor or Function Key
CSI 1 ; modifiers letter
- Specification
- Fix Keyboard Input on Terminals - Please, LeoNerd.org.uk
Every other page on this site is about bytes a terminal receives. This one is about bytes it sends: what a key produces when it is pressed. Here the usual encodings lose information. Tab is the same byte as Control and i; Control and i is the same as Control, Shift and i; Alt and a letter is Esc followed by the letter, so a program has to guess from timing whether Esc was pressed on its own; and a program with no real CSI parser misreads what xterm sends for Control and Up.
Fix Keyboard Input on Terminals is Paul Evans’s (LeoNerd’s) answer: an encoding in which every key press is sent as exactly one sequence, and every sequence means exactly one key press. It is an extension, not a replacement. A key that could be sent before is sent with the same bytes as before, and the new sequences cover only what could not be sent at all, or not distinctly. The name fixterms comes from the page’s address.
This summarizes the page as it was last modified on 15 May 2020, read from the Internet Archive’s copy of 4 November 2026. It asks program authors to read keys through its author’s libtickit, or to press the maintainers of libraries such as GNU Readline to adopt it, and asks terminal authors to send it. It defines no sequence for turning the encoding on: a terminal simply sends it.
Modifiers
Each of the three forms below carries the modifiers as its second parameter, as 1 plus a bit mask. The 1 is there because a missing parameter already means 1, so an unmodified key is 1 and the parameter can be left out.
| Modifier | Bit |
|---|---|
| Shift | 1 |
| Alt | 2 |
| Control | 4 |
| Modifiers | Value |
|---|---|
| none | 1, usually left out |
| Shift | 2 |
| Alt | 3 |
| Alt and Shift | 4 |
| Control | 5 |
| Control and Shift | 6 |
| Control and Alt | 7 |
| Control, Alt and Shift | 8 |
Characters: CSI code ; modifiers u
An unmodified character is sent as its UTF-8 bytes, as always: no UTF-8 character starts with a C0 or C1 byte, so it cannot be mistaken for a control. Shift does not count as a modifier for a character, since it is usually how the character was typed, as ! is. The simple cases stay as they were, Alt as an Esc prefix and Control as the character masked with 0x1f. What nothing could send before is sent as CSI codepoint ; modifiers u, the codepoint in decimal. CSI u was chosen because its final byte is in the private-use range, with no fixed meaning. For the letter a (97) and A (65):
| Unmodified | Alt | Control | Control and Alt | |
|---|---|---|---|---|
| without Shift | a | ESC a | 0x01 | ESC 0x01 |
| with Shift | A | ESC A | CSI 65 ; 5 u | CSI 65 ; 7 u |
The keys that collide with C0 controls are the point of it. With Control, i, m, [ and @ are sent in the new form, so that Tab, Enter, Esc and NUL are left meaning only themselves:
| Key | Sends | Not to be confused with |
|---|---|---|
Control and i | CSI 105 ; 5 u | Tab, 0x09 |
Control, Shift and i | CSI 73 ; 5 u | |
Control and m | CSI 109 ; 5 u | Enter, 0x0d |
Control, Shift and m | CSI 77 ; 5 u | |
Control and [ | CSI 91 ; 5 u | Esc, 0x1b |
Control and { | CSI 123 ; 5 u | |
Control and @ | CSI 64 ; 5 u | Control and Space, 0x00 |
The other C0 controls keep their single bytes, which older programs and the terminal driver depend on: Control and c is still 0x03, which the driver turns into SIGINT.
Enter, Esc, Backspace, Space and Tab
These have keys of their own, so Shift is a modifier here like any other, and with any modifier they are sent in the CSI u form with their ASCII code:
| Key | Unmodified | Shift | Control | Control and Shift |
|---|---|---|---|---|
| Enter | 0x0d | CSI 13 ; 2 u | CSI 13 ; 5 u | CSI 13 ; 6 u |
| Esc | 0x1b | CSI 27 ; 2 u | CSI 27 ; 5 u | CSI 27 ; 6 u |
| Backspace | 0x7f | CSI 127 ; 2 u | CSI 127 ; 5 u | CSI 127 ; 6 u |
| Space | 0x20 | CSI 32 ; 2 u | 0x00 | CSI 32 ; 6 u |
| Tab | 0x09 | CSI Z | CSI 9 ; 5 u | CSI 1 ; 5 Z |
Space and Tab keep the two forms terminals already send. Control and Space is NUL, and Shift and Tab is CSI Z, CBT as a terminal would read it, so Control, Shift and Tab becomes that sequence with a modifier. For Enter, Esc and Backspace the page gives only the Shift and Control columns; the Control and Shift column follows the same pattern.
Special keys: CSI number ; modifiers ~
Keys that are not characters are already sent as CSI number ~, and xterm and others already put the modifiers in a second parameter. fixterms keeps that, leaving the parameter out when there are no modifiers so that an unmodified key sends what it always has:
| Key | Number | Key | Number |
|---|---|---|---|
| Insert | 2 | F5 | 15 |
| Delete | 3 | F6 | 17 |
| Page Up | 5 | F7 | 18 |
| Page Down | 6 | F8 | 19 |
| Home | 7 | F9 | 20 |
| End | 8 | F10 | 21 |
| F1 | 11 | F11 | 23 |
| F2 | 12 | F12 | 24 |
| F3 | 13 | ||
| F4 | 14 |
Every sixth number, 10, 16, 22, 28 and so on, is skipped, because the original VT keyboards had physical gaps between their groups of five function keys at those places. Home, End and F1 to F4 are also sent in the shorter form below by some terminals, and the page asks a program to accept either.
Cursor and function keys: CSI 1 ; modifiers letter
Some keys are sent with a final letter of their own rather than ~, and the modifiers go in the second parameter of those too, after a first parameter of 1. Unmodified, both parameters are left out, giving CSI letter:
| Key | Letter | Key | Letter |
|---|---|---|---|
| Up | A | Home | H |
| Down | B | F1 | P |
| Right | C | F2 | Q |
| Left | D | F3 | R |
| End | F | F4 | S |
Sending CSI as one byte
As an extension, the page proposes that a terminal send CSI as the single 8-bit byte 0x9b and never as ESC [. Then a lone 0x1b can only be the Esc key, and a program no longer needs a timeout to tell Esc from the start of a sequence. It asks programs to accept 0x9b as CSI even when they do not know the terminal does this. See CSI for the two ways of writing it.
Where it falls short
kitty’s keyboard protocol says it is based on fixterms, and lists the problems it corrects in Bugs in fixterms. Among them:
- Esc can only be told apart by sending 8-bit controls, which are undesirable for other reasons.
- Unmodified F1 to F4 are sent as
SS3letter, notCSIletter, by any terminal newer than a VT52, and so are the arrow keys while cursor keys mode is set. The page does not mention cursor keys mode at all. - Control, Shift and Tab should be
CSI 9 ; 6 u: Shift and Tab is not a key of its own. - Control and Shift with a letter is sent as Control with the capital,
CSI 73 ; 5 u, losing the Shift. - There is no Super modifier, no way to send releases or repeats, no way to send both the shifted and the unshifted key, and numbers for only a few of the special keys.
CSI udoes have a meaning, SCORC, though only for a sequence sent to the terminal, so it does not collide with keys.
The page has slips of its own as well. It writes ESC [ as 0x1b 0x4b, where [ is 0x5b, and a sentence introducing its table of problem keys breaks off after “except for the awkward cases of”.
In terminals
xterm can send the CSI u form. Its resource formatOtherKeys, 0 by default, chooses how the keys enabled by modifyOtherKeys (XTMODKEYS) are sent: 0 as CSI 27 ; modifiers ; code ~, and 1 as CSI code ; modifiers u (xterm.man, modifyOtherKey). xterm added the resource at Paul Evans’s request, in patch 235 (2008), and since patch 398 (2025) a program can set it with XTFMTKEYS, CSI > 4 ; 1 f, and ask for it with CSI > 4 g. So xterm sends the fixterms form for the keys modifyOtherKeys covers, after a program asks for both, CSI > 4 ; 1 m or CSI > 4 ; 2 m and then CSI > 4 ; 1 f.
kitty’s protocol keeps the CSI u form and its modifier bits, adding Super, the event type and more, and a program turns it on with a flag rather than receiving it unasked. Its disambiguate flag, 1, sends Esc and keys with Control or Alt as CSI u, but leaves Enter, Tab and Backspace as they were.
libghostty-vt’s key encoder, outside the kitty protocol, combines xterm’s encodings with fixterms, on the grounds that both only extend what was sent before (key_encode.zig). A character with Control that has no C0 byte, and Control with i, m or [, are sent as CSI codepoint ; modifiers u, as fixterms asks (key_encode.zig, key_encode.zig). It departs from fixterms where kitty does: Control, Shift and m is sent as the lowercase letter with the Shift bit, CSI 109 ; 6 u, not as CSI 77 ; 5 u (test). Enter, Tab and Esc with modifiers are sent in xterm’s CSI 27 ; modifiers ; code ~ form rather than fixterms’s CSI u (function_keys.zig).
This site cannot press keys, so there are no cases here: the wasm terminal is given bytes to read, and fixterms is about what it would write.