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
Control-I to be ASCII Tab, as an example.
Since: Version 20221119-145034-49b9839f
The feature 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
the keyboard encoding is changed according to
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
Note that enable_csi_u_key_encoding and allow_win32_input_mode both take precedence over this behavior.
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
= 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
Windows) to be reported to the application.
enable_kitty_keyboard controls whether wezterm will honor the application requests to modify the keyboard encoding.
On Windows, allow_win32_input_mode
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