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

[galdawave]

Intent Summary: This change fixes a regression where tmux (especially when running over mosh) incorrectly reports a #ffffff background color, causing the CLI to inappropriately switch to a light theme. It mitigates this by ignoring #ffffff responses within tmux and updates the theme setup to suppress compatibility warnings if the user has explicitly disabled autoThemeSwitching.

🚨 Critical Concerns (P0/P1)

Action required before merging.

• packages/cli/src/utils/terminalTheme.test.ts:85: Strict typing violation. The use of as unknown as never to bypass type checking for getActiveTheme() is explicitly forbidden by the project's strict typing conventions. Import the Theme type and cast the mocked return value appropriately.

      vi.mocked(themeManager.getActiveTheme).mockReturnValue({
        name: 'Dracula',
        type: 'dark',
      } as Theme);

• packages/cli/src/utils/terminalTheme.test.ts:52 & :61: Strict typing violation. Avoid using as unknown as Config and as unknown as LoadedSettings to force partial mocks. Use Partial<Config> as Config (or a dedicated test factory) to maintain structural integrity without introducing unknown.

🧹 Refactoring & Nits (P2/P3)

Recommended improvements.

• packages/cli/src/utils/terminalTheme.test.ts: There is no test coverage for the default behavior where settings.merged.ui.autoThemeSwitching is undefined. Consider adding a brief test case to explicitly verify that the nullish coalescing fallback (?? true) correctly enables the warning.
• packages/cli/src/ui/utils/terminalCapabilityManager.ts: The heuristic this.terminalBackgroundColor === '#ffffff' hard-codes a fallback that will intercept legitimate white terminal backgrounds in tmux, dropping them to undefined (defaulting to a dark theme). This is a very reasonable design tradeoff given the severity of the mosh bug, but it does mean true-white tmux users must manually override their theme in config. The inline comment is good; no code change strictly required.

📝 Metadata Review

Feedback on PR description or commit message clarity.

• The PR description is excellent. It clearly identifies the Root Cause Analysis (RCA), outlines the fix, explicitly documents the design trade-off for complex terminal stacks, and provides comprehensive validation steps. The title is concise and accurately follows Conventional Commits.

[amelidev]

Intent Summary: This change fixes a regression where tmux (especially when running over mosh) incorrectly reports a #ffffff background color, causing the CLI to inappropriately switch to a light theme. It mitigates this by ignoring #ffffff responses within tmux and updates the theme setup to suppress compatibility warnings if the user has explicitly disabled autoThemeSwitching.

🚨 Critical Concerns (P0/P1)

Action required before merging.

• packages/cli/src/utils/terminalTheme.test.ts:85: Strict typing violation. The use of as unknown as never to bypass type checking for getActiveTheme() is explicitly forbidden by the project's strict typing conventions. Import the Theme type and cast the mocked return value appropriately.

      vi.mocked(themeManager.getActiveTheme).mockReturnValue({
        name: 'Dracula',
        type: 'dark',
      } as Theme);

• packages/cli/src/utils/terminalTheme.test.ts:52 & :61: Strict typing violation. Avoid using as unknown as Config and as unknown as LoadedSettings to force partial mocks. Use Partial<Config> as Config (or a dedicated test factory) to maintain structural integrity without introducing unknown.

🧹 Refactoring & Nits (P2/P3)

Recommended improvements.

• packages/cli/src/utils/terminalTheme.test.ts: There is no test coverage for the default behavior where settings.merged.ui.autoThemeSwitching is undefined. Consider adding a brief test case to explicitly verify that the nullish coalescing fallback (?? true) correctly enables the warning.
• packages/cli/src/ui/utils/terminalCapabilityManager.ts: The heuristic this.terminalBackgroundColor === '#ffffff' hard-codes a fallback that will intercept legitimate white terminal backgrounds in tmux, dropping them to undefined (defaulting to a dark theme). This is a very reasonable design tradeoff given the severity of the mosh bug, but it does mean true-white tmux users must manually override their theme in config. The inline comment is good; no code change strictly required.

📝 Metadata Review

Feedback on PR description or commit message clarity.

• The PR description is excellent. It clearly identifies the Root Cause Analysis (RCA), outlines the fix, explicitly documents the design trade-off for complex terminal stacks, and provides comprehensive validation steps. The title is concise and accurately follows Conventional Commits.

Working on concerns n.n thank you

[github-actions]

📊 PR Size: size/M

• Lines changed: 183
• Additions: +179
• Deletions: -4
• Files changed: 4

[amelidev]

@galz10 comments addressed!
This must be ready to merge :)

[galdawave]

Code Review: PR #27572

Intent Summary: This PR fixes a regression where the CLI incorrectly falls back to a light theme when running inside tmux (often via mosh), which commonly reports a false #ffffff terminal background. It also ensures that startup compatibility warnings are suppressed if the user explicitly disables autoThemeSwitching.

🚨 Critical Concerns (P0/P1)

Action required before merging.

• None. The heuristic is well-targeted, and the feature flag respect is a solid UX improvement. The logic is covered by tests.

🧹 Refactoring & Nits (P2/P3)

Recommended improvements.

• packages/cli/src/ui/utils/terminalCapabilityManager.test.ts:
  Instead of partially mocking the system-under-test with vi.spyOn(manager, 'isTmux').mockReturnValue(true), use vi.stubEnv('TMUX', '1') (and vi.unstubAllEnvs() or vi.stubEnv('TMUX', '') in other tests/hooks). This is the project convention for testing environment variable logic and ensures the actual isTmux implementation is covered.

• packages/cli/src/utils/terminalTheme.ts:
  The optional chaining in (settings.merged.ui?.autoThemeSwitching ?? true) is slightly redundant defensive code (AI bloat). settings.merged.ui is already accessed unconditionally a few lines earlier for settings.merged.ui.customThemes, so it is guaranteed to be defined. You can safely simplify this to:

      (settings.merged.ui.autoThemeSwitching ?? true)

📝 Metadata Review

Feedback on PR description or commit message clarity.

• The PR description is excellent. The RCA clearly explains the tmux 3.5+ limitation, and the design decisions section accurately reflects the trade-off made. Validation steps are concrete and reproducible.

[gemini-cli]

This pull request is being closed as it has been open for 14 days without a 'help wanted' designation. We encourage you to find and contribute to existing 'help wanted' issues in our backlog! Thank you for your understanding.

[gemini-cli]

This pull request is being closed as it has been open for 14 days without a 'help wanted' designation. We encourage you to find and contribute to existing 'help wanted' issues in our backlog! Thank you for your understanding.