modifyOtherKeys

Status: xterm.

modifyOtherKeys is xterm's mechanism for reporting modifier combinations that the legacy encoding cannot express, such as Ctrl-1, Ctrl-Shift-A, or Alt-Enter. It predates the Kitty keyboard protocol and is implemented by several other emulators, but the two output formats and the interaction with other xterm resources make it harder to consume than its successor.

Syntax

CSI > 4 ; Pv m      set modifyOtherKeys to Pv
CSI > 4 m           reset modifyOtherKeys to the resource default
CSI ? 4 m           XTQMODKEYS: query the current value
CSI > 4 ; Pv m      reply to XTQMODKEYS

Pv	Behavior
0	Disabled; legacy encoding only
1	Report modified keys except those with a well-established encoding
2	Report all modified keys, including Ctrl-letter combinations

Level 1 leaves Ctrl-C, Ctrl-letter, and similar bytes alone so that shells and job control keep working. Level 2 is for full-screen applications that want every combination.

CSI > 4 m with no value resets to the modifyOtherKeys resource, which is how xterm's own reset works; sending CSI > 4 ; 0 m forces level 0 instead.

Output formats

The formatOtherKeys resource chooses how xterm encodes a modified key:

formatOtherKeys	Sequence	Example: Ctrl-Shift-A
0 (default)	CSI 27 ; mod ; code ~	CSI 27 ; 6 ; 65 ~
1	CSI code ; mod u	CSI 65 ; 6 u

code is the Unicode code point of the key and mod is the xterm modifier parameter (one plus shift 1, alt 2, ctrl 4, meta 8). Format 1 is the form the Kitty protocol later adopted, which is why an application that parses CSI code ; mod u covers both. The 27 ~ form was chosen first because 27 is otherwise unused in the tilde key space.

An application cannot select the format from the wire; it must accept both.

Related resources

modifyCursorKeys and modifyFunctionKeys (CSI > 1 ; Pv m and CSI > 2 ; Pv m) control how modifiers attach to cursor and function keys. Their levels change whether the modifier goes in the second parameter (CSI 1 ; 5 A) or in a private prefix. Level 2, the default, produces the CSI 1 ; mod X form documented under legacy encoding.

modifyKeyboard (CSI > 0 ; Pv m) affects the numeric keypad and is rarely used.

Multiplexers

tmux's extended-keys option (on, off, or always) controls whether tmux requests modifyOtherKeys from the outer terminal and forwards the resulting sequences to the inner application in the format the inner application asked for. With extended-keys-format tmux can choose the 27 ~ or u form. Without it, tmux collapses modified keys back to the legacy encoding.

Pitfalls

• Level 2 makes Ctrl-C arrive as CSI 27 ; 5 ; 99 ~ rather than 0x03, so the kernel's ISIG handling no longer sees it; the application must handle interrupt itself.
• The two formats mean a parser needs both a ~ rule with leading 27 and a u rule.
• Some emulators answer CSI > 4 ; 2 m by enabling a different protocol entirely; detect with XTQMODKEYS or a Kitty protocol query rather than by assuming.

Probe

tools/query '\033[?4m'          # XTQMODKEYS
printf '\033[>4;2m'; cat -v; printf '\033[>4;0m'

Press Ctrl-1 or Ctrl-Shift-A inside cat -v and look for ^[[27; or ^[[49;5u-style output.

Sources

• XTerm Control Sequences
• XTerm manual
• tmux(1)

Compatibility

Feature support by terminal. Imported claims have not been reverified; unknown is not unsupported.

Feature / stable ID	Alacritty	Apple Terminal	ConPTY (conhost)	Contour	DomTerm	foot	Ghostty	iTerm2	kitty	Konsole	mintty	mlterm	PuTTY	Revenant	RLogin	st	tmux	rxvt-unicode	VTE	wayst	WezTerm	Windows Terminal	xterm	xterm.js
modifyOtherKeys csi-modify-other-keys	Unknown	Unknown	Unknown	Unknown	Unknown	SupportedImported · unverified	SupportedImported · unverified	SupportedImported · unverified	PartialImported · unverified	Unknown	SupportedImported · unverified	Unknown	Unknown	Unknown	Unknown	Unknown	SupportedImported · unverified	Unknown	Unknown	Unknown	SupportedImported · unverified	Unknown	SupportedImported · unverified	Unknown
XTMODKEYS set key modifier options csi-xtmodkeys	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown
XTQMODKEYS query key modifier options csi-xtqmodkeys	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown
Disable key modifier options csi-disable-key-modifier-options	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown