feat(cli): customizable keyboard shortcuts

[scidomino]

Summary

This PR implements customizable keyboard shortcuts by introducing a user configuration file (keybindings.json).

Details

Note: No documentation added just yet. There are a few more features I want to add before making it public.

• Refactored KeyBindingConfig to use a Map instead of a plain object for easier merging and overriding.
• Added loadCustomKeybindings() to load, parse (with comment-json for comment support), and validate (with zod) user-defined shortcuts.
• Replaced the hardcoded useKeyMatchers hook with a dynamic React Context (KeyMatchersProvider) to propagate custom bindings throughout the UI.
• Wired loading and error reporting (as warnings) into the main gemini.tsx entry point.
• Added comprehensive unit and integration tests.

Related Issues

For #21294

How to Validate

1. Run npm run start.
2. Observe the CLI starts with default keybindings.
3. Create a ~/.gemini/keybindings.json file with:

[
   { "command": "app.showErrorDetails", "key": "5" } ,
]

4. Restart the CLI. Check that the binding works.

5. Create a ~/.gemini/keybindings.json file with:

[
   { "command": "app.showErrorDetails", "key": "5" } ,
   { "command": "derp", "key": "a" } 
]

6. Restart the CLI. Check that invalid bindings emit a warning on startup and that the valid one DOES NOT WORK.

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: +2.75 kB (+0.01%)

Total Size: 26.5 MB

Filename	Size	Change
./bundle/gemini.js	26 MB	+2.75 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 improves the user experience by enabling customizable keyboard shortcuts within the CLI. By introducing a user-configurable keybindings.json file and a flexible React Context-based system, users can now tailor their interaction with the application to better suit their preferences. This change moves away from hardcoded keybindings, making the application more adaptable and user-friendly, while also ensuring robust error handling for custom configurations.

Highlights

• Customizable Keyboard Shortcuts: Introduced the ability for users to define custom keyboard shortcuts via a keybindings.json configuration file, enhancing user flexibility and personalization.
• Dynamic Keybinding Management: Refactored the internal KeyBindingConfig to use a Map for more efficient merging and overriding of keybindings, and replaced the static useKeyMatchers hook with a dynamic KeyMatchersProvider React Context to propagate custom bindings throughout the UI.
• Robust Configuration Loading: Implemented loadCustomKeybindings() to handle loading, parsing (with comment-json for comment support), and validating (with zod) user-defined shortcuts, including error reporting for invalid configurations.
• Core Integration and Testing: Integrated the custom keybinding loading and error reporting into the main gemini.tsx entry point and added comprehensive unit and integration tests to ensure reliability.

Changelog

• packages/cli/src/gemini.tsx
  • Imported KeyMatchersProvider and loadKeyMatchers.
  • Called loadKeyMatchers() asynchronously to retrieve custom keybindings and associated errors.
  • Emitted warnings for any errors encountered during keybinding loading.
  • Wrapped the main application container with KeyMatchersProvider to supply the loaded key matchers to the UI.
• packages/cli/src/ui/hooks/useKeyMatchers.ts
  • Removed the old useKeyMatchers.ts file.
• packages/cli/src/ui/hooks/useKeyMatchers.tsx
  • Added a new useKeyMatchers.tsx file.
  • Created KeyMatchersContext with defaultKeyMatchers as the default value.
  • Exported KeyMatchersProvider as a React Context provider to supply key matchers.
  • Implemented useKeyMatchers hook to consume the context, defaulting to defaultKeyMatchers if no provider is present.
• packages/cli/src/ui/key/keyBindings.test.ts
  • Imported vi, beforeEach, afterEach, os, path, fs, and Storage for testing file system interactions.
  • Updated references from defaultKeyBindings to defaultKeyBindingConfig.
  • Modified assertions to use Map.has() and Map.get() instead of direct object property access.
  • Added a new test suite for loadCustomKeybindings.
  • Implemented beforeEach and afterEach hooks to manage temporary directories and mock Storage.getUserKeybindingsPath.
  • Added tests for loading default bindings when no file exists, merging valid custom bindings, handling JSON with comments, and reporting validation errors for invalid schemas or key patterns.
• packages/cli/src/ui/key/keyBindings.ts
  • Imported fs, zod, comment-json, and Storage for file operations, schema validation, and JSON parsing.
  • Changed KeyBindingConfig type from a plain object to Map<Command, readonly KeyBinding[]>.
  • Converted defaultKeyBindings to defaultKeyBindingConfig, initialized as a Map.
  • Defined keybindingsSchema using zod for validating the structure of custom keybinding JSON.
  • Added loadCustomKeybindings asynchronous function to read, parse, validate, and merge user-defined keybindings with defaults, handling file not found and parsing errors.
• packages/cli/src/ui/key/keyMatchers.test.ts
  • Imported vi, beforeEach, afterEach, os, path, fs, and Storage for testing file system interactions.
  • Updated references from defaultKeyBindings to defaultKeyBindingConfig.
  • Modified custom config creation in tests to use new Map(defaultKeyBindingConfig) and config.set().
  • Added a new test suite for loadKeyMatchers integration.
  • Implemented beforeEach and afterEach hooks to manage temporary directories and mock Storage.getUserKeybindingsPath.
  • Added tests for loading matchers from a real file and handling invalid file content.
• packages/cli/src/ui/key/keyMatchers.ts
  • Updated imports to include loadCustomKeybindings.
  • Modified matchCommand to use config.get() for retrieving bindings from the Map.
  • Updated createKeyMatchers to accept KeyBindingConfig as a Map.
  • Updated defaultKeyMatchers to use defaultKeyBindingConfig.
  • Added loadKeyMatchers asynchronous function to load custom keybindings and create matchers, returning both matchers and any errors.
• packages/cli/src/ui/key/keybindingUtils.ts
  • Updated references from defaultKeyBindings to defaultKeyBindingConfig.
  • Modified formatCommand to use config.get() for retrieving bindings from the Map.
• packages/core/src/config/storage.ts
  • Added a static method getUserKeybindingsPath() to return the standardized path for the user's keybindings.json file.
• scripts/generate-keybindings-doc.ts
  • Updated references from defaultKeyBindings to defaultKeyBindingConfig.
  • Modified buildDefaultDocSections to use defaultKeyBindingConfig.get() for retrieving bindings from the Map.

Activity

• The pull request introduces customizable keyboard shortcuts, addressing issue Customizable keybindings #21294.
• The author has refactored keybinding configuration to use a Map and implemented a new loading mechanism.
• The changes include comprehensive unit and integration tests, as indicated by the checked pre-merge checklist item.
• The author noted that documentation is not yet added, planning to do so after more features are implemented.
• Validation steps are provided for testing default and custom keybindings, including scenarios with invalid configurations.

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 introduces customizable keyboard shortcuts by reading a keybindings.json file. The implementation is solid, featuring a refactor of the keybinding configuration to use a Map and a new React Context provider to make the key matchers available throughout the application. The loading mechanism is robust, with validation using zod and user-friendly error reporting for invalid configurations. The changes are well-tested with both unit and integration tests. I have reviewed the code and found no issues of high or critical severity.

[jacob314]

Thanks for this PR! The implementation of customizable keyboard shortcuts looks solid. The use of Zod for validation and React Context (KeyMatchersProvider) to propagate custom bindings throughout the UI are excellent choices.

I have a couple of suggestions and notes for future improvements:

Type Safety / Readability (Nitpick):
In packages/cli/src/ui/key/keyBindings.ts, the comment says // Config should be readonly, but the new KeyBindingConfig type uses Map<Command, readonly KeyBinding[]> which is mutable. Consider changing this to ReadonlyMap<Command, readonly KeyBinding[]> to enforce the immutability suggested by the comment. (Note: this is just a nit from Gemini CLI.)

Documentation & Default Keybindings Export:
For documentation purposes, it would be very helpful to add a command or utility that exports a default keybindings.json file exactly matching the default configuration from keyBindings.ts. Since users will likely want to edit that file, giving them a complete, valid starting template would be a great developer experience improvement.

Schema Export for Keybindings:
Looking at the slick way the settings schema was exported, it would be awesome to do something analogous for keybindings in a follow-up PR! Exporting a true JSON schema for keybindings.json would allow IDEs to provide auto-completion and validation out-of-the-box when users edit their custom shortcuts.

[jacob314]