^[control-codes live in libghostty-vt
View as Markdown

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.

ModifierBit
Shift1
Alt2
Control4
ModifiersValue
none1, usually left out
Shift2
Alt3
Alt and Shift4
Control5
Control and Shift6
Control and Alt7
Control, Alt and Shift8

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):

UnmodifiedAltControlControl and Alt
without ShiftaESC a0x01ESC 0x01
with ShiftAESC ACSI 65 ; 5 uCSI 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:

KeySendsNot to be confused with
Control and iCSI 105 ; 5 uTab, 0x09
Control, Shift and iCSI 73 ; 5 u
Control and mCSI 109 ; 5 uEnter, 0x0d
Control, Shift and mCSI 77 ; 5 u
Control and [CSI 91 ; 5 uEsc, 0x1b
Control and {CSI 123 ; 5 u
Control and @CSI 64 ; 5 uControl 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:

KeyUnmodifiedShiftControlControl and Shift
Enter0x0dCSI 13 ; 2 uCSI 13 ; 5 uCSI 13 ; 6 u
Esc0x1bCSI 27 ; 2 uCSI 27 ; 5 uCSI 27 ; 6 u
Backspace0x7fCSI 127 ; 2 uCSI 127 ; 5 uCSI 127 ; 6 u
Space0x20CSI 32 ; 2 u0x00CSI 32 ; 6 u
Tab0x09CSI ZCSI 9 ; 5 uCSI 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:

KeyNumberKeyNumber
Insert2F515
Delete3F617
Page Up5F718
Page Down6F819
Home7F920
End8F1021
F111F1123
F212F1224
F313
F414

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:

KeyLetterKeyLetter
UpAHomeH
DownBF1P
RightCF2Q
LeftDF3R
EndFF4S

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 SS3 letter, not CSI letter, 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 u does 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.

Every example on these pages runs in your browser, in libghostty-vt compiled to WebAssembly.