Textualize
Progressive enhancement for Kitty keyboard protocol is not enabled
Hi,
I want to be able to disambiguate shift-Enter from Enter. After some debugging I found out that although Kitty keyboard protocol supports it with its progressive enhancement features, it's not enabled.
Kitty keyboard protocol is enabled with self.write("\x1b[>1u") but the enhancements need to be enabled as well.
To enable reporting all keys as escape codes, I needed
self.write("\x1b[=8;u") after the protocol enabling line.
in the driver, and after that shift+enter started working. Also I saw somebody else reporting problem with shift+space, this one line change (2 lines if the inline driver adds it as well) fixes that as well, and a lot more keyboard combinations.
I also tried to enable all externsions (31 instead of 8), but that was not working.
This change is not 100% backwards compatible, but I believe it's the right choice for TUI applications, as most of them want access to much more key combos that this change enables.
We found the following entry in the FAQ which you may find helpful:
Feel free to close this issue if you found an answer in the FAQ. Otherwise, please give us a little time to review.
This project is developed and maintained by Will McGugan. Consider sponsoring Will's work on this project (and others).
This is an automated reply, generated by FAQtory
![github-actions[bot] avatar](https://avatars.githubusercontent.com/in/15368?v=4 "Published by a pub.dev verified publisher"){kind=small}
Textual does indeed support the Kitty key protocol.
If you filled out the issue template, I may be able offer more help.
After some debugging I found out that although Kitty keyboard protocol supports it with its progressive enhancement features, it's not enabled.
Just to back up what Will says, this code:
from textual.app import App
class KittyApp(App[None]):
BINDINGS = [
("enter", "enter"),
("shift+enter", "shift_enter"),
]
def action_enter(self) -> None:
self.notify("That was enter")
def action_shift_enter(self) -> None:
self.notify("That was shift and enter")
if __name__ == "__main__":
KittyApp().run()
running under Kitty does this:
Ditto under Ghostty and likely a bunch of other terminals.
Ditto under Ghostty and likely a bunch of other terminals.
Not Alacritty nor WezTerm for me (which both support this protocol).
Presumably because these terminals doesn't enable by default the progressive enhancements that @adamritter is talking about.
As Tom wrote, I am using Omarchy 2.0 which uses Alacrtitty as its terminal emulator.
On Tue, Aug 26, 2025, 3:26 PM TomJGooding @.***> wrote:
TomJGooding left a comment (Textualize/textual#6074) https://github.com/Textualize/textual/issues/6074#issuecomment-3224174674
Ditto under Ghostty and likely a bunch of other terminals.
Not Alacritty nor WezTerm for me (which both support this protocol).
Presumably because these terminals doesn't enable by default the progressive enhancements https://sw.kovidgoyal.net/kitty/keyboard-protocol/#progressive-enhancement that @adamritter https://github.com/adamritter is talking about.
— Reply to this email directly, view it on GitHub https://github.com/Textualize/textual/issues/6074#issuecomment-3224174674, or unsubscribe https://github.com/notifications/unsubscribe-auth/AN5SWAB7NT3WOHU5NVRQUYT3PRN6XAVCNFSM6AAAAACE2XGCXGVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTEMRUGE3TINRXGQ . You are receiving this because you were mentioned.Message ID: @.***>
Not Alacritty nor WezTerm for me (which both support this protocol).
Sorry, WezTerm actually does report shift+enter. I hadn't realised that you have to allow enabling the kitty keyboard in the config.
So maybe this is actually an issue with Alacritty?
Yes, it's in Alacritty, but actually it seems to be a non-complience for the other terminals.
According to the keyboard protocol (https://sw.kovidgoyal.net/kitty/keyboard-protocol/) the default even with enabling alternate screen mode is to remain compatible with legacy terminals:
,,To support these, in default mode, the terminal will emit legacy escape codes for compatibility. If a terminal program wants more robust key handling, it can request it from the terminal, via the mechanism described here. Each enhancement is described in detail below.''
Should I create a pull request by the way?
Yes, it's in Alacritty, but actually it seems to be a non-complience for the other terminals.
Are you suggesting the Kitty terminal isn't implementing its own protocol correctly? After reading its documentation again more thoroughly, there's still some parts I don't fully understand. But I don't think enter always simply emits the legacy escape code, otherwise why do other modifiers like ctrl +enter work even in Alacritty?
Should I create a pull request by the way?
To report all keys as escape codes? I'm not a maintainer but perhaps worth discussing what this might break?
I tested more the change of enabling Report all keys as escape codes mode, but it breaks even the space character, as Textual will start to think that it's not is_printable.
It would be great to implement is_printable for escaped printable characters, but I guess it's a bigger issue than just adding 1 line to the source code :(