feat(ui): hide cursor when terminal is unfocused

[Lyonk71]

Introduces a new useFocus hook to track terminal focus using ANSI escape codes.

This hook is used in the main App component to determine if the terminal window is active. The focus state is then passed to the InputPrompt component to conditionally render the cursor, hiding it when the window is not focused.

This improves the user experience by providing a clear visual indicator of the application's focus state.

Fixes #4007

TLDR

This PR hides the input cursor when the terminal window is not in focus. A new useFocus hook has been added to detect the terminal's focus state, and the InputPrompt now uses this state to control the cursor's visibility.

Dive Deeper

The core of this change is the new useFocus hook, which enables and disables terminal focus reporting using ANSI escape codes (CSI ? 1004 h and CSI ? 1004 l). When focus reporting is enabled, the terminal emits specific sequences on stdin when its focus state changes:

• \x1b[I (or CSI I) for focus-in
• \x1b[O (or CSI O) for focus-out

The hook listens for these sequences and maintains a boolean state (isFocused). This state is passed from the main App component down to the InputPrompt. The InputPrompt then uses this boolean to decide whether to render the cursor.

This approach is robust because it relies on a standard terminal feature and avoids trying to infer focus from other, less reliable events. The hook also includes comprehensive tests to ensure it correctly handles events and cleans up its listeners and terminal settings on unmount.

Reviewer Test Plan

1. Pull down this branch.
2. Run npm install to ensure all dependencies are up to date.
3. Start the Gemini CLI by running npm start.
4. Verify the cursor behavior:
   • With the terminal window active and focused, you should see the cursor in the input prompt as normal.
   • Click on another window or your desktop to make the terminal lose focus.
   • Expected result: The cursor in the input prompt should disappear.
   • Click back into the terminal window to give it focus again.
   • Expected result: The cursor should reappear.
5. Type a command and interact with the CLI to ensure no other functionality has been affected.

Testing Matrix

	Linux	macOS	Windows
npm run	✅	❓	❓
npx	❓	❓	❓
Docker	❓	❓	❓
Podman	❓	-	-
Seatbelt	❓	-	-

Linked issues / bugs

Fixes #4007

[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 @Lyonk71, 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 enhances the user interface of the CLI application by implementing a feature to automatically hide the input cursor when the terminal window loses focus. This is achieved through a new custom React hook that interacts with terminal focus reporting capabilities, providing a clearer visual indication of the application's active state.

Highlights

• New useFocus Hook: Introduced a new React hook, useFocus, which leverages ANSI escape codes (\x1b[?1004h and \x1b[?1004l) to enable and disable terminal focus reporting. It listens for \x1b[I (focus-in) and \x1b[O (focus-out) sequences on stdin to maintain a boolean state indicating whether the terminal is currently focused.
• Conditional Cursor Rendering: The main App component now utilizes the isFocused state from the useFocus hook and passes it down to the InputPrompt component. The InputPrompt has been modified to conditionally render the input cursor, hiding it when the terminal window is not focused, thereby improving user experience.
• Comprehensive Testing: A dedicated test file (useFocus.test.ts) has been added for the new useFocus hook, ensuring its correct behavior for focus events, state management, and proper cleanup of listeners and terminal settings on unmount.

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 in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.

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 issue 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 is currently in preview and 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 to provide feedback.

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 valuable UX improvement by hiding the cursor when the terminal is unfocused. A critical issue was identified in the stdin data handling that could cause the feature to fail silently under certain conditions. Addressing this will make the implementation much more robust.

[Lyonk71]

@jacob314 — just checking in to see if you’ve had a chance to take a look. It’s a light QoL tweak, but happy to hop on a quick call if that helps move it along.

[NTaylorMullen]

What an awesome change. @jacob314 FYI in case we want to utilize focus elsewhere. Thank you for the contribution @Lyonk71 !