Skip to content

Add Kitty keyboard protocol support - #5600

Open
mgrant0 wants to merge 6 commits into
masterfrom
kitty-keyboard-protocol
Open

mgrant0 wants to merge 6 commits into
masterfrom
kitty-keyboard-protocol

Conversation

@mgrant0

@mgrant0 mgrant0 commented Sep 14, 2026

Copy link
Copy Markdown
Contributor

Add kitty keyboard protocol support (KKP).

  • Clean implementation based on the published wire protocol
    (https://sw.kovidgoyal.net/kitty/keyboard-protocol/); no Kitty source code was
    used.
  • Integrated through extended-keys-format kitty.
  • Supports flags 1 and 8, Super (s-) and Hyper (H-).
  • Separate input-kitty.c and tty-kitty.c.
  • One saved protocol state per main/alternate screen.
  • Eager outer-terminal negotiation, restored on detach.
  • Release events are safely discarded.
  • Existing key masks remain unchanged.
  • Xterm and Kitty negotiation are mutually exclusive.
  • New files use tmux’s ISC license with the configured Git identity.

This PR follows #5405 (Add kitty keyboard protocol support (finish #4912). All the comments were hopefully addressed.

This work adds the new extended-keys-format kitty which now supports xterm, csi-u, and now kitty.

This PR uses the emacs style naming convention:

  • S- = Shift
  • C- = Control
  • M- = Meta/Alt
  • s- = Super
  • H- = Hyper

Also note that kitty-keys-terminal.sh cannot run under the regress
Makefile, which uses env -i and so removes DISPLAY and HOME, and make the
Kitty test file modes match the rest of regress.
@gabehowe

gabehowe commented Sep 18, 2026

Copy link
Copy Markdown

I've tried using this under Ghostty and pressing Shift+Space writes ";2u".

edit:
I failed to set extended-keys-format to kitty.

@mgrant0

mgrant0 commented Sep 19, 2026

Copy link
Copy Markdown
Contributor Author

@gabehowe try this:

Add these lines to test.conf:

set -s extended-keys on
set -s extended-keys-format kitty

then start tmux. Run these commands and let me know what they output:

./tmux display -p 'client=#{client_key_mode}'
./tmux command-prompt -k 'display-message -p "tmux got: %%"'

Then press shift-space.

Asuming you are in the directory where you compiled this branch, you need to run the tmux you compiled, hence ./tmux.

You should see the mode "Kitty 1" and you should see "S-space".

Note, I am currently trying to see if I can get each client to discover if it supports kitty or xterm or csi-u or just plain ascii, so you may not need to specificy set the extended-keys-format to kitty if I can figure that out.

@gabehowe

Copy link
Copy Markdown

Both kitty and Ghostty return client=Ext for the first command and nothing for the second command until I focus out and focus in, at which point it displays tmux got: FocusIn.

I've just tested this on kitty and it doesn't have this behavior, so perhaps it's somehow Ghostty specific?.

@mgrant0

mgrant0 commented Sep 19, 2026

Copy link
Copy Markdown
Contributor Author

Huh, it's not what I see. Are you reattaching to an existing tmux server? Also, you can't turn on kitty after you reattach, you need to start your tmux -f test.conf or start tmux like this:

tmux -L kbtest -f /dev/null start-server \; set -s extended-keys on \; set -s extended-keys-format kitty \; new

@mgrant0

mgrant0 commented Sep 19, 2026

Copy link
Copy Markdown
Contributor Author

I have added autodetection for kitty in this PR: #5615

@gabehowe

Copy link
Copy Markdown

Huh, it's not what I see. Are you reattaching to an existing tmux server? Also, you can't turn on kitty after you reattach, you need to start your tmux -f test.conf or start tmux like this:

tmux -L kbtest -f /dev/null start-server \; set -s extended-keys on \; set -s extended-keys-format kitty \; new

Looks like I was attaching to an existing server. Now I get client = Kitty 1 and tmux got: S-Space and shift-space doesn't paste ;2u.
It also looks like I failed to change my config to use extended-keys-format kitty.
With it done correctly it works perfectly under ghostty in vim/nvim.

I'm sorry to have taken up your time.

@nicm nicm moved this from Not Started to For Review in Open Issues & PRs Sep 21, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: For Review

Development

Successfully merging this pull request may close these issues.

3 participants