feat(ui): improve startup warnings UX with dismissal and show-count limits

[spencer426]

Summary

Improved the UX for startup warnings by making them dismissible via any keypress and limiting the number of times low-priority "nag" warnings are shown to the user.

Details

• Defined WarningPriority (Low, High) and StartupWarning interface in @google/gemini-cli-core.
• Updated getCompatibilityWarnings and getUserStartupWarnings to return StartupWarning objects.
• Designated terminal compatibility (true-color) and home-directory warnings as Low priority.
• Modified Notifications component to:
  • Listen for any keypress to dismiss visible warnings.
  • Track show counts for low-priority warnings in persistentState.
  • Limit low-priority warnings to a maximum of 3 appearances.
• Updated all relevant tests to match the new warning structure and verified dismissal logic.

Warning ID	Priority	Display Logic	Suppression Logic
256-color	High	Shown if terminal supports < 256 colors	Always shows on startup
windows-10	High	Shown on Windows 10 (not 11)	Always shows on startup
jetbrains-terminal	High	Shown inside JetBrains IDE terminals	Always shows on startup
root-directory	High	Shown if running in system / root	Always shows on startup
startup-*	High	Shown if defined in local system warning files	Always shows on startup
true-color	Low	Shown if < 24-bit color (Auto-hidden on Mac Terminal)	Stops showing after 3 times
home-directory	Low	Shown if running in user ~ home directory	Stops showing after 3 times

Related Issues

Related to internal UX feedback regarding excessive terminal compatibility warnings.

How to Validate

1. Run the CLI in a terminal that doesn't support true color (or mock it to return false for supportsTrueColor()).
2. Verify the warning appears at the bottom.
3. Press any key (e.g., 'a') and verify the warning disappears immediately while the key is still processed by the input.
4. Restart the CLI 3 times; the warning should no longer appear after the 3rd time.
5. High-priority warnings (like running in root directory) should still always appear until dismissed.

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

[gemini-code-assist]

Summary of Changes

Hello @spencer426, 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 enhances the user experience for startup warnings in the CLI. By introducing dismissible warnings and limiting the frequency of low-priority notifications, it aims to reduce user friction and improve overall usability. The changes also include a robust system for categorizing and managing different types of warnings, ensuring that critical information is presented effectively while less urgent messages do not become intrusive.

Highlights

• Improved Startup Warnings UX: Startup warnings can now be dismissed by any keypress, and low-priority warnings are limited to a maximum of 3 appearances to reduce user 'nagging'.
• Warning Prioritization: Introduced WarningPriority (Low, High) and StartupWarning interface to categorize warnings, with terminal compatibility and home-directory warnings designated as Low priority.
• Persistent State Tracking: The system now tracks the show count for low-priority warnings in persistentState to enforce appearance limits across sessions.
• Compatibility Checks: Added new compatibility checks for Windows 10, JetBrains terminals, and true-color support, generating warnings where applicable.
• New UI Setting: A new setting ui.showCompatibilityWarnings was added, allowing users to control the display of compatibility-related startup warnings.

Changelog

• docs/cli/settings.md
  • Added documentation for the new ui.showCompatibilityWarnings setting.
• docs/get-started/configuration.md
  • Included details for the new ui.showCompatibilityWarnings configuration option.
• package-lock.json
  • Removed the peer: true property from several dependency entries, likely due to dependency resolution updates.
• packages/cli/src/config/settingsSchema.ts
  • Added showCompatibilityWarnings boolean setting to the UI category of the settings schema.
• packages/cli/src/gemini.tsx
  • Imported createHash for generating unique warning IDs.
  • Updated startupWarnings type to StartupWarning[] and mapped raw string warnings to StartupWarning objects with high priority and unique IDs.
  • Imported StartupWarning type and WarningPriority enum.
• packages/cli/src/ui/AppContainer.tsx
  • Updated the startupWarnings prop type to accept StartupWarning[] objects.
• packages/cli/src/ui/components/Notifications.test.tsx
  • Updated imports to use renderWithProviders and createMockSettings.
  • Modified Notifications tests to handle StartupWarning objects instead of plain strings.
  • Added tests for incrementing show counts for low-priority warnings.
  • Added tests for filtering out low-priority warnings that exceed the maximum show count.
  • Implemented tests for dismissing warnings via keypress.
• packages/cli/src/ui/components/Notifications.tsx
  • Imported useMemo and useKeypress hooks.
  • Introduced MAX_STARTUP_WARNING_SHOW_COUNT constant.
  • Implemented dismissed state and visibleWarnings memoization to filter warnings based on priority and show counts.
  • Added useEffect hook to increment show counts for low-priority warnings in persistentState.
  • Integrated useKeypress to allow dismissal of visible startup warnings.
  • Updated the rendering of startup warnings to display a warning icon and use visibleWarnings.
• packages/cli/src/ui/components/snapshots/Notifications.test.tsx.snap
  • Updated snapshots to reflect changes in error and update notification rendering due to UI adjustments.
• packages/cli/src/ui/contexts/AppContext.tsx
  • Updated the startupWarnings property in AppState interface to be of type StartupWarning[].
• packages/cli/src/utils/persistentState.ts
  • Added startupWarningCounts property to PersistentStateData interface to store warning display counts.
• packages/cli/src/utils/userStartupWarnings.test.ts
  • Imported getCompatibilityWarnings and WarningPriority for testing.
  • Updated mocks for @google/gemini-cli-core to include getCompatibilityWarnings and WarningPriority.
  • Modified tests to expect StartupWarning objects with id, message, and priority properties.
  • Added tests to verify inclusion and exclusion of compatibility warnings based on settings.
• packages/cli/src/utils/userStartupWarnings.ts
  • Imported getCompatibilityWarnings, WarningPriority, and StartupWarning types.
  • Updated WarningCheck interface to include a priority property.
  • Assigned WarningPriority.Low to homeDirectoryCheck and WarningPriority.High to rootDirectoryCheck.
  • Modified getUserStartupWarnings to return StartupWarning[] and include compatibility warnings based on the showCompatibilityWarnings setting.
• packages/core/src/index.ts
  • Exported all functions and types from the new utils/compatibility.js module.
• packages/core/src/utils/compatibility.test.ts
  • Added a new test file for compatibility utility functions.
  • Included tests for isWindows10, isJetBrainsTerminal, and supportsTrueColor detection.
  • Added comprehensive tests for getCompatibilityWarnings to cover various environmental scenarios.
• packages/core/src/utils/compatibility.ts
  • Added a new utility file for environment compatibility checks.
  • Defined isWindows10 to detect Windows 10 OS.
  • Defined isJetBrainsTerminal to detect JetBrains IDE terminals.
  • Defined supportsTrueColor to check for 24-bit color support.
  • Introduced WarningPriority enum (Low, High) and StartupWarning interface.
  • Implemented getCompatibilityWarnings to return a list of relevant compatibility warnings based on the detected environment.
• schemas/settings.schema.json
  • Added a new schema definition for ui.showCompatibilityWarnings.

Activity

• The pull request introduces new UI features and settings, requiring validation on different platforms and scenarios as outlined in the 'How to Validate' section.
• Tests were added and updated to cover the new warning structure and dismissal logic.
• No explicit reviewer comments or approvals have been recorded yet.

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 new ui.showCompatibilityWarnings setting, defaulting to true, which controls the display of terminal and OS compatibility warnings. The core changes involve refactoring how startup warnings are handled: they are now represented by a structured StartupWarning object (containing an ID, message, and priority) instead of simple strings. This allows for more granular control, such as limiting the display count of low-priority warnings to three times and enabling dismissal of all warnings via keypress. The package-lock.json file was also updated, primarily removing "peer": true from various dependency entries. Documentation and tests were updated to reflect these changes, including new tests for warning prioritization, display limits, and dismissal.

[jacob314]

One minor improvement: in packages/cli/src/ui/components/Notifications.tsx, the useKeypress hook was being provided an inline arrow function as its callback. This causes the hook's useEffect dependencies to change on every render, which in turn causes it to unsubscribe and re-subscribe the event listener repeatedly. I fixed this by wrapping the callback in useCallback.

[github-actions]

Size Change: +3.19 kB (+0.01%)

Total Size: 25.2 MB

Filename	Size	Change
./bundle/gemini.js	25.1 MB	+3.19 kB (+0.01%)

ℹ️ View Unchanged

Filename	Size
./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}

[spencer426]

One minor improvement: in packages/cli/src/ui/components/Notifications.tsx, the useKeypress hook was being provided an inline arrow function as its callback. This causes the hook's useEffect dependencies to change on every render, which in turn causes it to unsubscribe and re-subscribe the event listener repeatedly. I fixed this by wrapping the callback in useCallback.

Done

[jacob314]

[jacob314]

The changes look great. Preflight passes locally, tests are comprehensive, and the implementation aligns well with the stated goals. The use of useCallback with useKeypress is a good catch. LGTM!