# Fix Keyboard Input on Terminals (fixterms)

> 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.

- **Sequence:** `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](http://web.archive.org/web/20261104071439/https://www.leonerd.org.uk/hacks/fixterms/)

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](http://web.archive.org/web/20261104071439/https://www.leonerd.org.uk/hacks/fixterms/).
It asks program authors to read keys through its author's
[libtickit](https://www.leonerd.org.uk/code/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](https://control-codes.page/csi/cbt/index.html.md) 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](https://control-codes.page/esc/csi/index.html.md) for the two ways of
writing it.

## Where it falls short

kitty's [keyboard protocol](https://control-codes.page/csi/kitty-keyboard/index.html.md) says it is based on
fixterms, and lists the problems it corrects in
[Bugs in fixterms](https://sw.kovidgoyal.net/kitty/keyboard-protocol/#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](https://control-codes.page/modes/decckm/index.html.md) 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](https://control-codes.page/csi/decslrm/index.html.md), 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](https://control-codes.page/csi/xtmodkeys/index.html.md)) are sent: `0` as `CSI 27 ; modifiers ; code ~`,
and `1` as `CSI code ; modifiers u`
([`xterm.man`](https://github.com/ThomasDickey/xterm-snapshots/blob/xterm-411a/xterm.man#L4046-L4056),
[`modifyOtherKey`](https://github.com/ThomasDickey/xterm-snapshots/blob/xterm-411a/input.c#L759-L782)).
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](https://control-codes.page/csi/xtfmtkeys/index.html.md), `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`](https://github.com/ghostty-org/ghostty/blob/919dca5c848d43a489a4cb2e1feade016f0fa2db/src/input/key_encode.zig#L321-L326)).
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`](https://github.com/ghostty-org/ghostty/blob/919dca5c848d43a489a4cb2e1feade016f0fa2db/src/input/key_encode.zig#L483-L524),
[`key_encode.zig`](https://github.com/ghostty-org/ghostty/blob/919dca5c848d43a489a4cb2e1feade016f0fa2db/src/input/key_encode.zig#L845-L850)).
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](https://github.com/ghostty-org/ghostty/blob/919dca5c848d43a489a4cb2e1feade016f0fa2db/src/input/key_encode.zig#L2454-L2466)).
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`](https://github.com/ghostty-org/ghostty/blob/919dca5c848d43a489a4cb2e1feade016f0fa2db/src/input/function_keys.zig#L187-L259)).

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.

---

This is the Markdown version of <https://control-codes.page/proposals/fixterms/>. On that page every validation case runs live in libghostty-vt, the terminal emulation core of Ghostty, compiled to WebAssembly.
