Skip to content

Support kitty keyboard protocol basic mode#888

Closed
jechol wants to merge 1 commit intoruby:masterfrom
jechol:jechol/kitty-keyboard-protocol
Closed

Support kitty keyboard protocol basic mode#888
jechol wants to merge 1 commit intoruby:masterfrom
jechol:jechol/kitty-keyboard-protocol

Conversation

@jechol
Copy link

@jechol jechol commented Mar 10, 2026

Summary

  • enable kitty keyboard protocol basic mode in the ANSI I/O gate lifecycle
  • normalize kitty CSI u key sequences into existing Reline key semantics
  • keep Ctrl-C working by routing it through a dedicated interrupt action
  • add parser, ANSI, and PTY integration tests for kitty keyboard protocol behavior

Testing

  • ./miniruby ./tool/runruby.rb --extout=.ext -- -Igems/src/reline/lib gems/src/reline/test/reline/test_key_stroke.rb
  • ./miniruby ./tool/runruby.rb --extout=.ext -- -Igems/src/reline/lib gems/src/reline/test/reline/test_ansi.rb
  • ./miniruby ./tool/runruby.rb --extout=.ext -- -Igems/src/reline/lib gems/src/reline/test/reline/test_reline.rb

Context

This fixes broken key handling in terminals that enable kitty keyboard protocol basic mode.

A concrete regression target is the VS Code integrated terminal after the January 2026 VS Code 1.109 release notes announced kitty keyboard protocol support and the experimental terminal.integrated.enableKittyKeyboardProtocol setting:
https://code.visualstudio.com/updates/v1_109

That release notes page says the feature "has been implemented and will be rolling out to stable this release" and that it "requires the program running in the terminal to support the protocol and request to enable it when it runs". In practice, this means irb/reline currently mis-handle keys such as Backspace, Escape, Alt-modified keys, and Ctrl-C in the VS Code terminal unless the setting is disabled.

This PR makes reline opt into kitty keyboard protocol basic mode and interpret the resulting CSI u key sequences so irb keeps working correctly in that environment.

@tompng
Copy link
Member

tompng commented Mar 10, 2026

Thank you for the pull request.

This requires the program running in the terminal to support the protocol and request to enable it when it runs.

I don't think this part is saying that all program should support kitty protocol. If that's true, every existing old program breaks. The feature is disabled by default and need to enable it if a program want to use it.
There should be a precondition: "If your program want to get benefit of this update, it requires to support the protocol and ..."

I think it's great to support kitty keyboard protocol input. Assumed scenario is: Some program enabled it but forgot to disable it or crashed. Reline launched after that receives kitty keyboard protocol input.
However, Reline don't need to enabling it with "\e[>1u" until Reline implements a behavior that need to distinguish TAB and \C-i input.

@jechol
Copy link
Author

jechol commented Mar 10, 2026

Thanks, that makes sense.

What I wanted to highlight is that, in practice, current VS Code stable seems to expose kitty-coded input to users already. On my setup, irb in the VS Code integrated terminal only works normally when "terminal.integrated.enableKittyKeyboardProtocol": false is set.

I can reproduce this in current VS Code, but not in current Cursor on the same machine and shell setup, so this looks more like recent VS Code terminal behavior than just a shell-specific issue. There also seem to be similar user reports after the recent VS Code update:
https://www.reddit.com/r/vscode/comments/1rm9l7d/vscode_terminal_broken_after_last_update_cant/

Another subtlety is that Reline may see kitty CSI u input even if the current irb/reline process did not enable it itself, because the terminal or PTY session may already be left in that mode by the terminal host or an earlier process.

So I agree these are two separate questions:

  • whether Reline should actively enable kitty protocol itself
  • whether Reline should defensively understand kitty CSI u input when it is already being sent

Even if we drop the "\e[>1u" part, I think supporting CSI u input is still useful for real-world compatibility with current VS Code terminals.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants