Keyboard Encoding

When input that doesn't match a key assignment is processed, it is encoded into a byte stream and sent to the PTY associated with the program that is running in the active pane.

The default encoding scheme used by wezterm is xterm compatible, but there are some configuration options that can modify the encoding.

The standard xterm compatible encoding generates events for key presses (but not releases) and can represent the set of keys that existed on terminal hardware of the 1980's.

That scheme has worked well for quite some time, but has some ambiguity due to the way that the Control modifier "shifts" the ASCII representation of keypresses like Control-I to be ASCII Tab, as an example.

xterm modifyOtherKeys

Since: Version 20221119-145034-49b9839f

The functionality described in this section requires version 20221119-145034-49b9839f of wezterm, or a more recent version.

When wezterm receives the sequence CSI >4;Nm, where N is 0, 1 or 2, the keyboard encoding is changed according to modifyOtherKeys, which causes certain modified keys to be encoded as described in xterms docs, making it possible for applications to distinguish between the modified and unmodified key presses.

Note that enable_csi_u_key_encoding and allow_win32_input_mode both take precedence over this behavior.

CSI-u/fixterms/libtickit

Fix Keyboard Input on Terminals is an attempt at resolving the ambiguous encoding and doing a better job at representing more modifiers. It's not a perfect attempt as there are a number of issues with it.

You can enable support for this encoding by setting enable_csi_u_key_encoding = true, however, it is not recommended as it does change the behavior of some keys in backwards incompatible ways and there isn't a way for applications to detect or request this behavior.

See also: enable_csi_u_key_encoding.

Note that allow_win32_input_mode takes precedence over this option.

Kitty Keyboard Protocol

The Kitty terminal extended and enhanced the CSI-u based encoding scheme with its Comprehensive keyboard handling protocol.

The kitty protocol allows applications to request varying degrees of enhancement over the standard encoding scheme and also allows for more modifier keys (notably: CMD/Super/Windows) to be reported to the application.

enable_kitty_keyboard controls whether wezterm will honor the application requests to modify the keyboard encoding.

Windows

On Windows, allow_win32_input_mode defaults to true which causes wezterm to listen for an escape sequence generated by the ConPTY layer of Windows to enable Win32 Input Mode.

In this mode, key release events as well as events that can distinguish between positional (left/right) modifier keys are generated and this mode provides the best compatibility with win32 console applications such as Far Manager.

allow_win32_input_mode takes precedence over enable_csi_u_key_encoding.