feat: prompt users to run /terminal-setup in supported terminals

[JagjeevanAK]

Summary

One-time prompt asking users if they'd like to run /terminal-setup when running inside a supported terminal (VS Code, Cursor, Windsurf, Antigravity) that doesn't have multiline keybindings configured. This is a fresh implementation addressing all feedback from the closed PR #16235.

Closes #16005

Details

• useTerminalSetupPrompt hook in terminalSetup.ts — encapsulates all prompt logic, keeping AppContainer.tsx minimal (2 lines: import + call)
• shouldPromptForTerminalSetup() — checks kitty protocol, terminal detection, and existing keybindings to determine if prompting is useful
• TERMINAL_DATA map + getSupportedTerminalData() — replaces switch statements, shared between shouldPromptForTerminalSetup() and terminalSetup()
• hasOurBinding() helper — DRY shared function for checking shift+enter/ctrl+enter keybinding presence
• useRef for cancelled flag — fixes the critical bug from feat: prompt users to run /terminal-setup with yes/no #16235 where useEffect cleanup ran on re-render, cancelling the async flow before the user could respond "yes"
• persistentState('terminalSetupPromptShown') — ensures the prompt is only shown once per user
• debugLogger.debug() in all catch blocks instead of silently swallowing errors
• 8 new tests for shouldPromptForTerminalSetup

Related Issues

Closes #16005
Supersedes #16235

How to Validate

1. Run tests: npx vitest run packages/cli/src/ui/utils/terminalSetup.test.ts (18 tests pass)
2. Build: npm run build --workspace=packages/cli
3. Manual test in VS Code terminal without existing keybindings:
   • Run gemini — should see a Y/N prompt asking to configure terminal
   • Select "Yes" — keybindings should be written
   • Run gemini again — prompt should NOT appear (persistent state)
4. Manual test in a terminal with keybindings already configured — prompt should NOT appear
5. Manual test outside VS Code/Cursor/Windsurf/Antigravity — prompt should NOT appear

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

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[gemini-code-assist]

Summary of Changes

Hello @JagjeevanAK, 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 introduces a user-friendly feature that proactively guides users in supported terminals to configure essential multiline input keybindings. By detecting the terminal environment and checking for existing configurations, the system now intelligently prompts users to run /terminal-setup only when it's beneficial and hasn't been shown before. This enhancement improves the initial user experience by streamlining the setup process for interactive terminal usage.

Highlights

• One-Time Terminal Setup Prompt: Introduced a one-time prompt for users in supported terminals (VS Code, Cursor, Windsurf, Antigravity) to configure multiline keybindings via /terminal-setup.
• Modular Prompt Logic: Implemented the prompt logic within a new useTerminalSetupPrompt React hook for better modularity and separation of concerns.
• Intelligent Prompt Determination: Developed shouldPromptForTerminalSetup() to intelligently determine when the prompt is necessary, considering existing keybindings and terminal capabilities.
• Refactored Utilities: Refactored terminal data and keybinding checks into shared utilities (TERMINAL_DATA, getSupportedTerminalData(), hasOurBinding()) to reduce code duplication.
• Critical Bug Fix: Resolved a critical bug from a previous attempt (feat: prompt users to run /terminal-setup with yes/no #16235) by using useRef to prevent premature cancellation of the async prompt flow during React re-renders.
• Persistent State Tracking: Ensured the prompt is displayed only once per user by utilizing persistentState to track its display status.
• Enhanced Error Logging: Improved error handling by adding debugLogger.debug() to catch blocks for better visibility into potential issues.
• Comprehensive Testing: Added comprehensive new tests for the shouldPromptForTerminalSetup logic, covering various scenarios and edge cases.

Changelog

• packages/cli/src/ui/AppContainer.tsx
  • Imported the new useTerminalSetupPrompt hook.
  • Called useTerminalSetupPrompt to integrate the terminal setup prompt into the application's main container.
• packages/cli/src/ui/utils/terminalSetup.test.ts
  • Imported shouldPromptForTerminalSetup for testing.
  • Added mocks for React's useEffect and useRef, persistentState, requestConsentInteractive, and debugLogger to facilitate testing of the new hook and logic.
  • Introduced new test cases for shouldPromptForTerminalSetup covering various scenarios like kitty protocol status, terminal detection, and keybinding file states (missing, empty, valid, invalid JSON, partial bindings).
• packages/cli/src/ui/utils/terminalSetup.ts
  • Added imports for React hooks (useEffect, useRef), persistentState, requestConsentInteractive, and related types.
  • Defined TERMINAL_DATA constant and getSupportedTerminalData function to centralize terminal metadata.
  • Created hasOurBinding helper function to check for specific keybindings in an array.
  • Implemented shouldPromptForTerminalSetup function to determine if a terminal setup prompt is needed based on terminal capabilities and existing keybindings.
  • Refactored the terminalSetup function to utilize getSupportedTerminalData instead of a switch statement.
  • Defined TERMINAL_SETUP_CONSENT_MESSAGE and formatTerminalSetupResultMessage for prompt and result formatting.
  • Introduced useTerminalSetupPrompt React hook, which manages the one-time interactive prompt for terminal setup, incorporating persistentState and useRef for cancellation handling.
• packages/cli/src/utils/persistentState.ts
  • Extended the PersistentStateData interface to include terminalSetupPromptShown, allowing the application to track whether the terminal setup prompt has been displayed.

Activity

• This pull request is a fresh implementation that addresses all feedback provided on the previously closed PR feat: prompt users to run /terminal-setup with yes/no #16235.
• Specifically, feedback from @scidomino regarding removing unnecessary checks, moving prompt logic, and using map lookups was incorporated.
• A critical bug identified by @scidomino related to useEffect cleanup prematurely cancelling async flow was fixed using useRef.
• Feedback from @gemini-code-assist on DRYing up keybinding checks and logging errors in catch blocks was also addressed.

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 a one-time prompt for users in supported terminals to configure multiline input, which is a great usability improvement. The implementation is well-structured, moving the logic into a dedicated useTerminalSetupPrompt hook and refactoring the terminal configuration to be more data-driven. The addition of comprehensive tests for the new logic is also a strong point.