Thanks. Will take a closer look some time soon. Only thing is I think this should be rolled into extended-keys/extended-keys-format somehow rather than adding a new option.

A few other comments:

• input-keys.c is getting kind of big, so perhaps make input-kitty.c and move your kitty-specific functions in there?

• Please remove references to "legacy" key codes, it is unclear, use either VT10x or extended like the existing comments, depending which you want to refer to.

• I think Super-, Hyper-, RealMeta- are too long. I'd go with Sp-, Hy-, Rm-, although I don't like the name "Real Meta" much anyway so I'd probably just drop it for now, how many keyboards have both Alt and Meta?

• You can remove (kitty keyboard protocol) from the comments for KEYC_ since these keys may exist in other encodings.

• Similar to above, I think this is making tty-keys.c too big and a new file tty-kitty.c would be better.

• I think "function key" is the more usual term rather than "functional key".

• 8 seems a bit excessive for KITTY_KBD_STACK_MAX and it is making struct screen a good bit bigger. TBH I would only keep two (current and saved).

It looks good otherwise, apart from a few style nits which can be easily fixed later. I didn't test it yet though.

Thanks!

I'm having a second run at it. I've been testing it - mostly good, found a couple of things. Incorporating these and will then attack your points before others can take a 2nd look.

Ok, I've had a 2nd pass at it now. I've gone over it, fixed a few small things and added some tests and so forth. I've also incorporated the feedback - apart from somehow rolling it into extended-keys / extended-keys-format. That one I don't feel very certain around an approach for. Let me know what you think @nicm

btw, the python test script is there as I didn't manage to produce a bash version. It's feel like it should be possible but I failed at it.

Code looks good to me, a couple of minor things:

• In the new files, input-kitty.c and tty-kitty.c, you should change the copyright line at the top of the file to your name and email address (if you don't want to include the email address, you can leave it out), and to 2026 instead of 2007.

• In input_csi_dispatch, variable declarations should go at the top of the file, not inside inner blocks. So that is int flags, raw_flags, dropped, count, mode, flagset, raw_flagset;. If the code or number of variables is getting unwieldly, use helper functions.

• Is there a rationale for making this a separate kitty-keys option? Why don't we just try to turn it on if we think the terminal supports it and extended-keys is on? It falls back sensibly to the standard extended keys, doesn't it?

• I don't know there is any need for Dskitk/Enkitk. This is not something different terminals are going to implement in a different way so users or terminals will need to redefine. I think we could just hardcode the escape sequences.

It's a bit of a pity they chose to occupy four modifiers to CSI u for this one feature when one would have been fine (or even extending CSI m further), but there is little to be done about that now.

I tried it lightly in ghostty, at least the normal extended keys seem to still work (such as C-BSpace, C-1 etc). My keyboard doesn't really have any media keys or similar, and Super/Hyper are taken by the window manager, so I'll have to take your word for it that that sort of thing works.

With this PR, if I run the following on Kitty 0.46 or Ghostty 1.3, most keys do not register in the resulting window (including normal letters). I'm using macOS Sequoia. I'm also using fish 4.5.0 (though I'm not sure where this matters).

./tmux -Ltest -f /dev/null set -s kitty-keys always \; set -s extended-keys always \; new

I think kitty-keys do not play well with extended-keys.

I am also getting some separate problems with keys like ^D. When I ran

./tmux -Ltest -f /dev/null set -s kitty-keys always  \; new dash

pressing ^D results in ^[[100;5u being printed.

Here is a log where I start tmux with dash with both extended-keys and kitty-keys and press abc^d, then have to use ^bx to quit (but the bug with ^d is present even without extended-keys):

tmux-server-85653.log

According to AI:

The interesting part starts at line 33149. Lines 26029-33079 are terminal detection/startup. Here's the summary:

• Line 33149-33737: a, b, c received as plain bytes, written to pane, routed through input_key_mode1 (which falls through to extended-keys encoding instead of raw bytes)
• Line 33747-33762: C-d received as \033[100;5u, written to pane via input_key_kitty (sends CSI u to dash instead of raw 0x04)
• Line 33833-33834: C-b received as \033[98;5u (tmux prefix)
• Line 34079: x — the quit

So lines ~33149–33762 are the key part — about 600 lines. You could trim the log to roughly lines 33100–34100 for a focused excerpt.

(but I didn't trim it :)

Here is AI's theory on what the bug with ^D is:

Look at the key flow for C-d:

1. Ghostty sends \033[100;5u to tmux (100='d', 5=Ctrl+1)
2. tmux parses this and creates key code 0x200000000064 — that's d with a KEYC_CTRL-like flag (the 0x2000000000 prefix)
3. In input_key_kitty at line 197, mod is computed from this key and is non-zero (Ctrl)
4. At line 263, onlykey is 0x64 ('d'), which is <= 0x7f, so we enter that block
5. At line 268, mod != 0, so the early return is skipped
6. Lines 273-275: it encodes as \033[100;5u and sends that to dash

The missing logic: in disambiguate mode (flag 1 only), C-d should be sent as the raw byte 0x04 (C0 control), not CSI u. The kitty spec says that Ctrl+letter combinations that produce C0 codes (0x01-0x1a) should use the legacy byte in disambiguate mode. There's no check here for "Ctrl is the only modifier and the key maps to a C0 code → send the C0 byte instead."

I was also sorry to discover that "release events" are discovered. My primary use-case for this was a terminal app that uses those (it's a weird one, Ki editor, it has so-called "momentary layers"). But, according to the same AI, fixing that would be a large project.

Actually, I'm experiencing the bug where typing "abc" doesn't work even without turning on kitty-keys, just with this PR and

 ./tmux -vv -Ltest -f /dev/null set -s extended-keys always \; new fish

It works fine without this PR, at d32088b.

This does only become a problem with fish, though (I have fish 4.5.0), using dash here avoids the bug.

But this is a bigger problem because this breaks existing users with extended-keys set to always in their config, of which I am one (whether that's wise is a different question, I don't remember what didn't work without that setting).

Oh, and thank you for working on it!

@nicm thanks for the input! I'll have a look at the smaller adjustments. In terms of folding into extended-keys it seemed "safer" to make it an opt-in for this specific case and being able to tell that mode and this mode apart. But I think you're right it could be combined. Up for attempting that.

@ilyagr thanks for giving it a spin. And it draws out that I just tried this in ghostty on linux (minor testing in kitty), with kitty-keys on. I have completely glossed over any manual testing without kitty-keys being on. I think kitty-keys always is generally a bad idea - you'll get key codes sent to apps that don't support them etc. First port of call is some manual testing (outside the existing regression tests) with kitty-keys off, and with both extended-keys and kitty-keys on. I put the PR forward mostly to gage interest - I'm aware it needs a lot more testing!

My quick test (zsh user, don't belive foot comes into this), on ghostty 1.2.3:

1. kitty-keys always and extended-keys always = gridlock, no input works
2. kitty-keys on and extended-keys always = works ok in my limited testing
3. kitty-keys off and extended-keys always = works ok in my limited testing
4. kitty-keys always and extended-keys on = works ok in my limited testing
5. kitty-keys on and extended-keys on = works ok in my limited testing

So the path that's (definitely) broken is always+always. In general testing I'm not sure it's good to ever use kitty-keys always - it'll send the wrong key codes to various applications that don't know how to handle them. I haven't taken the time to understand what extended-keys really does - but as a first step I'll fix the gridlock case.

I'd be inclined to remove the always for kitty-keys if it doesn't make sense.

It's OK to keep kitty-keys for now and we can think about how/if to integrate it with the other options later.

This removes the conflict as an intermediate step. I think I agree that it does not make sense to allow always for kitty-keys - I can't see a case where it makes sense. I'm far from an expert here though - very much open to bigger brains with more experience in this field opining!

Addressed the items raised in your previous comment @nicm . Unifying kitty-keys and extended-keys is the item left out, and the one I feel a bit nervous around attempting.

I'd love for people to test this more, and for more knowlegable people to comment if it makes sense to remove kitty-keys = always. I think we need to build a bit of confidence via more wide spread testing before confirming all is well. In my daily usage I haven't found any issues, but there's a lot of corner cases out there I'm sure given the rich domain of tty interactions..

You can't reproduce the issue where ^D doesn't work with kitty-keys off and extended-keys always? Nor the one where nothing works with fish + kitty-keys off and extended-keys always?

You can't reproduce the issue where ^D doesn't work with kitty-keys off and extended-keys always? Nor the one where nothing works with fish + kitty-keys off and extended-keys always?

It reproduces for me with alacritty + zsh. It's even somewhat stranger. ^D doesn't work right after tmux was started. But it starts working after Vim (which enabled the Kitty Keyboard Protocol) exited...

So this is why I'm thinking that it basically never makes sense to set kitty-keys = always. With this setting you will ALWAYS have the kitty protocol active, meaning that anything running that doesn't speak it, will not get the inputs it expects. In this mode, Ctrl-D works fine if the thing you run inside of of your session support the protocol, otherwise it'll get "garbage" keys. If you run with kitty-keys = on then you will only send the extended protocol keys when the running application actually supports the protocol, and if it doesn't support it the expected codes are sent. The sane path.

I strongly suggest testing with kitty-keys = on. And as I suggested before, I think it makes sense to not even support = always and I remove that from the PR. I only added it by symmetry to how the extended-keys was done, but now I think it likely doesn't make sense.

Ah, okay. I set kitty-keys = always in the first place because Vim wasn't working with kitty-keys = on. So this warrants a second look.

Vim requests the Kitty Keyboard Protocol by emitting [=1;1u. If I read https://sw.kovidgoyal.net/kitty/keyboard-protocol/#ctrl-mapping right this should enable disambiguate escape codes, the same way as setting kitty-keys = always does unconditionally.

Let's take ctrl-3 as example key combination. When I request disambiguate escape codes in plain Alacritty I get:

% printf '\033[=1;1u'
% cat -v
^[[51;5u

This is a CSI escape code as specified by the Kitty Keyboard Protocol. Key 51 is "3", modifier is 1 + 4 for ctrl.

But when I do the same in tmux I get:

% printf '\033[=1;1u'
% cat -v
^[[27u

This is a legacy escape code. ctrl combines with "3" maps to Key 27 which is Escape.

So even if disambiguate escape codes where requested, a legacy escape is send. This looks like a bug in tmux. Or am I missunderstanding something?

Probably a bug! I'll look at it.

@Yamagi I've attempted to deal with the outer vs inner kitty mode with this latest commit. Any feedback welcome!

Hello @sundbp and thanks a lot for your efforts on this feature!

I did a quick test on your latest commit with ./tmux -Ltest -f /dev/null set -s kitty-keys on \; set -s extended-keys on \; new and it looks good to me. I didn't do a thorough test to be honest, just a few key combinations that I knew were not working before and they all give the expected results in and out of tmux

$ printf '\e[>1u'

# Pressing in sequence: Ctrl-/ Ctrl-. Shift-Enter Ctrl-3
$ cat -v
^[[47;5u ^[[46;5u ^[[13;2u ^[[51;5u

Great to hear. I'm not sure what the appropriate path to getting enough confidence to merge this looks like.. I gave it a go as it seemed that missing kitty keyboard mode is a growing "gap" in tmux, but I'm far from an expert in this space. As it touches on fairly central key code interpretation paths, even in off mode we still touch new code (that should do nothing :)) in the main input paths - hence it it does seem high impact in case I've messed something up. Review by others and real world testing is only thing I can think of.

I can comfirm that Vim is now working fine with kitty-keys on.

I gave it a go as it seemed that missing kitty keyboard mode is a growing "gap" in tmux, but I'm far from an expert in this space. As it touches on fairly central key code interpretation paths, even in off mode we still touch new code (that should do nothing :)) in the main input paths - hence it it does seem high impact in case I've messed something up.

For me this is one of the most important additions to tmux in the last years. While I can work with legacys keys and modifyOtherKeys work around the most annoying problems, the Kitty Keyboard Protocol is another level. Reliable mappings for ctrl-$number alone are a huge advantages.

I'll use this branch on my work laptop over the next few days. I'll report any bugs I encounter and give feedback if there are no remaining problems for me.

I'll use this branch on my work laptop over the next few days. I'll report any bugs I encounter and give feedback if there are no remaining problems for me.

I've been doing the same and I think I found an issue with compose key and accent letters.

This is what I get outside of tmux when I type RightAlt + ` + e (RightAlt is my compose key):

printf '\e[>1u'; cat -v
è

And this is what I get in tmux (kitty-keys on, extended-keys on) with the same combination:

printf '\e[>1u'; cat -v
^[[1107339459u

Great - I don't type those kinds of characters so hadn't tried this. I pushed a fix for this case - please see if it behaves as expected @cippaciong

Awesome, works now!

printf '\e[>1u'; cat -v
èéẁç°ü

Thanks @sundbp for the quick fix

Hey! 👋 I'm super excited to try this out as I'm using dte which supports both the legacy mode (modifyOtherKeys) as well as Kitty's keyboard protocol.

I don't think it makes sense to ever set kitty-keys = always as it would require all applications you interact with to also support and understand the escape sequences emitted by the protocol. Normally, the running application asks the terminal to enable the protocol for it specifically and then it's turned off again once you quit the program.

I'm going to report back soon!

@nicm I've made an attempt at folding kitty keys into extended-keys here, and looked at the 4 bits. The fix to the input-keys.sh test works nicely for me - thanks!

I haven't looked at the binding issue. I'm not sure I see that one clearly enough to have a solution in mind!

Looks good. I would probably have added them to extended-keys so it is on, off, always, kitty, but I don't mind using -format instead.

The point with the key bindings is that I should be able to do for example bind Sp-Left swapp -L or bind VolumeDown kill-pane in tmux and if the terminal supports Kitty keys, the bindings should work even if no pane has requested them.

This means tmux needs to enable enough for its own use immediately - you can see this with the existing extended keys, tmux turns them on in tty_update_features and then "downgrades" them to X10 keys if the application in a pane has not turned them on

In an ideal world, any combination of terminal and application would work as far as possible, so tmux would request either Kitty keys or extended keys (depending on the extended-keys and extended-keys-format options) from the terminal and if the key was being passed to a pane, translate depending what the application inside the pane wants (so X10, extended mode 1, mode 2 or Kitty). But I am OK with only a subset working - perhaps only support these combinations:

That is, if tmux is configured for standard extended keys, but the application requests Kitty, the request would be ignored and X10 keys only would be sent. And similarly if tmux is configured for Kitty keys and the application requests standard extended keys. I think that is fine.

Thanks for the feedback. I'll try to take that onboard and see what I can do.

Worth noting I haven't done a ton of manual testing post the re-organization. Anyone following along is very welcome to refresh and give it a spin!

@nicm had a first stab at the remaining parts. not done too much manual testing yet - but thought I'd share to sense check direction.

Only did a quick test but works much better for me, I can bind keys only supported by Kitty like Pause and they work immediately.

The idea looks right, tmux always turns on Kitty keys. I guess you will need to mediate between what tmux needs and what the active pane wants in terms of flags? Like we do for SGR mouse mode (and extended keys eg we always use mode 2).

I think Super-, Hyper-, RealMeta- are too long. I'd go with Sp-, Hy-, Rm-, although I don't like the name "Real Meta" much anyway so I'd probably just drop it for now, how many keyboards have both Alt and Meta?

FWIW, there's some prior art for the format of these modifiers in Emacs. I opted to use the same s- (Super) and H- (Hyper) prefixes in dte, since the existing C-, M- and S- ones already matched. Not sure if the convention matters much, but just thought I'd mention it here.

No strong opinion from me. Happy to go with emacs conventions if that has general support.

I don't really mind, I think s is a bit of a poor choice for Super but if you want to match emacs go for it.

Great work! Really miss this feature. Hope it will cover Ctrl+RET too

Is this now ready to go or what is left to do? Thanks

Is there a reason why release events are discarded? Is the support for the protocol intended to be partial at the moment?

@nicm I dropped the ball. The last thing I had in mind was the modifiers.

@musjj I don't t think there was a reason. My memory is now pretty rusty - any particular situations and code locations you have in mind?

@sundbp

It's this line (also mentioned in your original PR description):

https://github.com/tmux/tmux/pull/4912/changes#diff-fd5d00eeffbec5a58a55c15bca5c5a0677d099df7999049afe30d42604228bb5R853-R856

I'm working a TUI that needed to detect key release events, so I'm wondering why it's getting dropped in this PR.

@musjj I can't recall a reason right now.. I'm guessing I may have found issues with it and "punted" on it as not a super common use case. Any chance you could experiment with your use case to see if you can get support for it working?

Ok tested your PR and key release events are not reported, unfortunately. Modifier key events are reported though, so your PR is already partially working.

I tried to tweak your PR here: musjj@5ddf17d

But I'm still not getting any key release events. Do you have any idea why it's not working?

@musjj thanks for doing the leg work. I need to re-engage with this PR as I've forgotten a lot of it by now :/ I'll try to have a look at it and wrap this one up asap.