fix(cli): handle tmux false positive background detection

[amelidev]

Summary

Fixes a regression where Gemini CLI incorrectly detects a light terminal background (#ffffff) when running inside tmux (especially via mosh), leading to inappropriate theme switching and compatibility warnings.

https://b.corp.google.com/issues/490058141

Details

• RCA: tmux 3.5+ reports #ffffff as a default background color when it cannot query the host terminal. The CLI previously treated this as a high-confidence hardware report.

Fix

• Added a heuristic in TerminalCapabilityManager to ignore #ffffff reports when running inside tmux.
• Updated setupTerminalAndTheme to suppress compatibility warnings if ui.autoThemeSwitching is disabled by the user.

Design Decisions

Chosen to ignore pure white specifically in tmux as it's the standard false-positive report. Respecting the user's explicit auto-switch setting provides a clean escape hatch for complex terminal stacks.

Related Issues

Fixes the reported terminal background detection regression.

How to Validate

1. Run a dark terminal with tmux.
2. Run gemini-cli.
3. Verify that the CLI does not default to a light theme.
4. Verify that no 'Theme might look incorrect' warning appears if Dracula (or any dark theme) is selected.
5. Verify /bug output reports Terminal Background: undefined (or the actual color if passthrough is working, but NOT #ffffff if it's a false positive).

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:
  • Linux
    • npm run

[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 improves the CLI's terminal background detection by introducing a heuristic to filter out common false positives reported by tmux. Additionally, it refines the theme compatibility check to respect user-defined configuration settings, ensuring that warnings are only triggered when automatic theme switching is active.

Highlights

• Tmux False Positive Handling: Added a heuristic to ignore the #ffffff background color reported by tmux 3.5+ when it cannot determine the actual host terminal color, preventing incorrect light theme application.
• Theme Compatibility Logic: Updated the terminal theme setup to respect the 'autoThemeSwitching' setting, ensuring warnings about theme incompatibility are only emitted when automatic switching is enabled.
• Testing: Added comprehensive unit tests for terminal capability detection in tmux and validated the theme compatibility warning logic.

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 the 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 counterproductive. 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.

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. ↩

[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]

Code Review

This pull request introduces a heuristic to ignore #ffffff terminal background color reports in tmux to prevent false positives (e.g., over mosh), and updates theme setup logic to respect the autoThemeSwitching setting. It also adds corresponding unit tests. The review feedback suggests restoring the modified global process.stdin.isTTY property in the new test file using an afterEach hook to prevent test environment pollution.

[amelidev]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces a heuristic to ignore #ffffff background color detections in tmux to prevent false positives (e.g., over mosh), and updates theme setup logic to respect the autoThemeSwitching setting. It also adds corresponding unit tests for these changes. A review comment suggests using optional chaining and nullish coalescing to safely access settings.merged.ui.autoThemeSwitching to prevent potential runtime errors if ui is undefined.

[amelidev]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces a heuristic to ignore #ffffff (white) terminal background color detections when running inside tmux, preventing false positives (e.g., over mosh) that could lead to applying an incorrect light theme. It also updates the theme setup logic to respect the autoThemeSwitching setting before warning about theme incompatibilities. Comprehensive unit tests have been added for both the terminal capability manager and the terminal theme setup. No review comments were provided.