Detection, done like sync:

- ESC[?u goes to every VT100-like terminal at attach, whatever the
  options.
- A reply turns on a new kittykeys terminal feature. Users can force
  it on or off with terminal-features kittykeys, including kittykeys@
  to turn it off.
- Changing extended-keys now takes effect immediately for attached
  clients (options.c).

Use, per client, when extended-keys is on: Kitty for clients that have
kittykeys, modifyOtherKeys for clients with extkeys, VT10x otherwise.

Pane side:

- Applications can request either protocol; Kitty wins if one asks for
  both.
- Each application gets what it asked for, whichever client typed the
  key.
- ESC[?u is answered truthfully.
- The per-client gate is gone. window.c and popup.c are simply
  master's versions again.

extended-keys always is back to its master meaning, forcing
modifyOtherKeys mode 1 only. Forcing Kitty on every program would have
sent bash ESC[97;5u for Ctrl-A.

extended-keys-format kitty is still accepted, but now behaves the same
as csi-u.
This commit is contained in:
Michael Grant
2026-09-19 07:32:57 +01:00
parent 7545954d00
commit d85329e5f0
17 changed files with 117 additions and 212 deletions

79
tmux.1
View File

@@ -4914,19 +4914,29 @@ If enabled, the server will exit when there are no attached clients.
.Op Ic on | off | always
.Xc
Controls how modified keys are reported.
For the
.Ic csi\-u
and
.Ic xterm
formats, this controls the
When enabled,
.Nm
uses the Kitty keyboard protocol with terminals which support it, and the
.Ic modifyOtherKeys
.Xr xterm 1
resource.
For the
.Ic kitty
format, this controls the progressive keyboard protocol enhancements.
resource with other terminals which support extended keys.
Each client uses the best that its terminal supports, so clients with different
terminals may be attached at the same time.
.Pp
When set to
Programs inside panes may request either the Kitty keyboard protocol or
.Ic modifyOtherKeys ,
and keys are sent to each program in the form it requested, whichever client
they were typed on.
The Kitty keyboard protocol can report the Super and Hyper modifiers, whose key
name prefixes are
.Ql s-
and
.Ql H- ;
its disambiguate and report-all enhancements are supported.
.Pp
For
.Ic modifyOtherKeys ,
when set to
.Ic on ,
the program inside the pane can request one of two modes: mode 1 which changes
the sequence for only keys which lack an existing well-known representation; or
@@ -4935,7 +4945,8 @@ When set to
.Ic always ,
modes 1 and 2 can still be requested by applications, but mode 1 will be forced
instead of the standard mode.
This applies only to applications inside panes and does not change what
This applies only to applications inside panes; it does not force the Kitty
keyboard protocol or change what
.Nm
requests from the terminal.
When set to
@@ -4944,19 +4955,12 @@ this feature is disabled and only standard keys are reported.
.Pp
.Nm
will always request extended keys itself if the terminal supports them.
When the
.Ic kitty
format is selected, it is preferred separately for each client; clients which
do not support it use standard extended keys if available, or standard VT10x
keys otherwise.
Input from standard extended-key clients is translated to Kitty encoding for
applications which have requested it.
A Kitty keyboard state query reflects the clients attached to the window at
the time of the query; if none are attached, the requested state is reported.
Applications are not notified if client support changes after the reply.
Support for the Kitty keyboard protocol is detected when a client attaches.
See also the
.Ic kittykeys
and
.Ic extkeys
feature for the
features for the
.Ic terminal\-features
option, the
.Ic extended\-keys\-format
@@ -4968,22 +4972,9 @@ variables.
.It Xo Ic extended\-keys\-format
.Op Ic csi\-u | xterm | kitty
.Xc
Selects the format for reporting modified keys to applications.
The
.Ic kitty
format uses the Kitty keyboard protocol and supports the Super and Hyper
modifiers.
Their key name prefixes are
.Ql s-
and
.Ql H- .
The disambiguate and report-all enhancements are supported; event types,
alternate keys and associated text are not requested.
For the
.Ic csi\-u
and
.Ic xterm
formats, this is the equivalent of the
Selects the format for reporting modified keys to programs which request
.Ic modifyOtherKeys .
This is the equivalent of the
.Ic formatOtherKeys
.Xr xterm 1
resource.
@@ -4995,10 +4986,11 @@ and as
.Ql \[ha][[65;6u
when set to
.Ic csi\-u .
With
.Ic kitty ,
it will be reported as
.Ql \[ha][[97;6u .
.Ic kitty
is accepted for compatibility and is the same as
.Ic csi\-u ;
programs which request the Kitty keyboard protocol receive it whatever this
option is set to.
.It Xo Ic focus\-events
.Op Ic on | off
.Xc
@@ -5150,6 +5142,9 @@ Ignore function keys from
and use the
.Nm
internal set only.
.It kittykeys
Supports the Kitty keyboard protocol.
This is added automatically if the terminal answers the Kitty keyboard query.
.It margins
Supports DECSLRM margins.
.It mouse