feat(cli): support literal character keybindings and extended Kitty protocol keys

[scidomino]

Summary

Updates the keybinding system and KeypressContext to support literal character bindings (e.g., %, @, +) instead of forcing users to use shift+key. It also adds extensive support for the Kitty Keyboard Protocol (CSI-u), including function keys F13-F35, numpad digits (while preserving insertable typing), and various modifier keys.

Details

• Modified KeypressContext to programmatically handle Kitty protocol function keys, numpad keys, and modifiers.
• Added legacy mapping for f13-f20 sequences.
• Updated keyBindings.ts to allow any single Unicode character as a valid keybinding (via [...key].length === 1), making it robust for international keyboard layouts.
• Removed redundant explicitly typed single-character keys from VALID_KEYS.

Related Issues

Related to #21294

How to Validate

1. Add a keybinding with a literal character (like {"command": "basic.cancel", "key": "%"}) in your keybindings.json. Run the app, press shift+5 for %, and verify the command executes.
2. If using a terminal that supports the Kitty Keyboard Protocol (e.g., Ghostty, Kitty, iTerm2 with the setting enabled), test function keys f13 through f35 or numpad digits, ensuring they trigger bound commands while numpad numbers correctly type numbers when no command is bound.

Pre-Merge Checklist

• Updated relevant documentation and README (if needed)
• Added/updated tests (if needed)
• Noted breaking changes (if any)
• Validated on required platforms/methods:
  • MacOS
    • npm run
    • npx
    • Docker
    • Podman
    • Seatbelt
  • Windows
    • npm run
    • npx
    • Docker
  • Linux
    • npm run
    • npx
    • Docker

[github-actions]

Size Change: +1.72 kB (+0.01%)

Total Size: 26.5 MB

Filename	Size	Change
./bundle/gemini.js	26 MB	+1.72 kB (+0.01%)

ℹ️ View Unchanged

Filename	Size
./bundle/node_modules/@google/gemini-cli-devtools/dist/client/main.js	221 kB
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/_client-assets.js	227 kB
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/index.js	11.5 kB
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/types.js	132 B
./bundle/sandbox-macos-permissive-open.sb	890 B
./bundle/sandbox-macos-permissive-proxied.sb	1.31 kB
./bundle/sandbox-macos-restrictive-open.sb	3.36 kB
./bundle/sandbox-macos-restrictive-proxied.sb	3.56 kB
./bundle/sandbox-macos-strict-open.sb	4.82 kB
./bundle/sandbox-macos-strict-proxied.sb	5.02 kB

_{compressed-size-action}

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the CLI's keybinding system by introducing support for direct literal character keybindings and integrating comprehensive handling for the Kitty Keyboard Protocol. These changes improve user experience by allowing more intuitive key assignments and expanding compatibility with advanced terminal emulators, providing a richer and more customizable interaction model.

Highlights

• Literal Character Keybindings: The keybinding system now supports literal character bindings (e.g., '%', '@', '+') directly, removing the need for 'shift+key' combinations for these characters.
• Kitty Keyboard Protocol Support: Extensive support for the Kitty Keyboard Protocol (CSI-u) has been added, including function keys F13-F35, numpad digits (while preserving insertable typing), and various modifier keys.
• KeypressContext Enhancements: The KeypressContext has been modified to programmatically handle Kitty protocol function keys, numpad keys, and modifiers, improving key detection and processing.
• Flexible Keybinding Validation: The keyBindings.ts file has been updated to allow any single Unicode character as a valid keybinding, making the system more robust for international keyboard layouts and custom key definitions.

Activity

• No human activity has been recorded on this pull request yet.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request significantly enhances keyboard input handling, particularly for the Kitty Keyboard Protocol (CSI-u sequences). It introduces a new KITTY_CODE_MAP to parse these sequences into specific key names and actions, including support for extended functional keys (F13-F35), various special keys (e.g., capslock, pausebreak), and numpad keys. The emitKeys function was refactored to leverage this new mapping and correctly interpret CSI-u sequences, distinguishing between printable ASCII characters and special key codes. Corresponding test cases have been added to KeypressContext.test.tsx to validate the recognition of these new key sequences. Additionally, the KeyBinding class in keyBindings.ts was updated to refine key validation, separating single-character keys from a new VALID_LONG_KEYS set, which now encompasses the expanded range of supported function and numpad keys.