Skip to content

feat(cli): invert context window display to show usage#20071

Merged
keithguerin merged 11 commits intomainfrom
invert-context-used
Mar 3, 2026
Merged

feat(cli): invert context window display to show usage#20071
keithguerin merged 11 commits intomainfrom
invert-context-used

Conversation

@keithguerin
Copy link
Contributor

@keithguerin keithguerin commented Feb 23, 2026

Closes #20070

Inverts the context window display throughout the app to show used percentage instead of left. Rationale: Align with quota, other Google products, and competitors.

Changes

  • UI: Updated ContextUsageDisplay.tsx to show 'X% context used'.
image
  • Coloring: Dynamic yellow warning in footer when compressionThreshold is reached; red at 100%.
  • Notifications:
    • Simplified overflow warning: 'might exceed the context window limit (M tokens left)'.
    • Succinct Compression Notification:
      • Before: IMPORTANT: This conversation exceeded the compression threshold. A compressed context will be sent for future messages (compressed from: {original} to {new} tokens).
      • After: Context compressed from X% to Y%. Change threshold in /settings. (Single line, multi-colored).
image
  • Settings: Renamed to 'Context Compression Threshold' for better discoverability.
image
  • Documentation: Updated settings docs and changelog.
  • Tests: Updated all unit tests and snapshots to match the new format.

@keithguerin keithguerin requested review from a team as code owners February 23, 2026 20:56
@gemini-code-assist
Copy link
Contributor

Summary of Changes

Hello @keithguerin, I'm Gemini Code Assist1! 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 related to context window management by shifting the display paradigm from 'tokens left' to 'tokens used'. This change, coupled with dynamic visual cues and clearer notifications, aims to provide users with a more immediate and understandable grasp of their model's context consumption, helping them manage their interactions more effectively and proactively avoid exceeding limits.

Highlights

  • Inverted Context Window Display: The UI now displays the percentage of context 'used' instead of 'left', providing a more intuitive understanding of current token consumption.
  • Dynamic Context Usage Coloring: The context usage display in the footer now dynamically changes color: yellow when the compression threshold is reached, and red when 100% of the context window is used.
  • Simplified Overflow and Compression Notifications: Overflow warnings have been made more succinct, indicating 'tokens left'. Compression notifications now provide a clear, concise message along with the compression threshold displayed as both a decimal and percentage.
  • Renamed Settings Option: The 'Compression Threshold' setting has been renamed to 'Context Compression Threshold' for improved clarity and discoverability within the settings.
  • Documentation and Test Updates: All relevant documentation, including changelogs and settings references, has been updated to reflect these changes. Unit tests and snapshots were also updated to match the new display formats and logic.
Changelog
  • docs/changelogs/index.md
    • Updated the description for configurable compression to include decimal with percentage display.
  • docs/cli/settings.md
    • Updated the description for 'Hide Context Window Percentage' to refer to 'usage percentage'.
    • Renamed 'Compression Threshold' to 'Context Compression Threshold' in the model settings table.
  • docs/reference/configuration.md
    • Updated the description for ui.footer.hideContextPercentage to refer to 'usage percentage'.
  • packages/cli/src/config/settingsSchema.ts
    • Added an optional unit property to the SettingDefinition interface to allow for display units.
    • Updated the description for hideContextPercentage to refer to 'usage percentage'.
    • Renamed the label for compressionThreshold to 'Context Compression Threshold'.
  • packages/cli/src/ui/components/Composer.tsx
    • Removed the terminalWidth prop from the ContextUsageDisplay component.
  • packages/cli/src/ui/components/ContextUsageDisplay.test.tsx
    • Switched to renderWithProviders for component rendering.
    • Removed the terminalWidth prop from test cases.
    • Updated test assertions to check for 'context used' instead of 'context left'.
    • Removed an unnecessary mock for settings.
  • packages/cli/src/ui/components/ContextUsageDisplay.tsx
    • Modified to display 'percentage used' instead of 'percentage left'.
    • Removed the terminalWidth prop, simplifying the component's dependencies.
    • Implemented dynamic text coloring (yellow/red) based on context usage and compression threshold.
  • packages/cli/src/ui/components/Footer.test.tsx
    • Updated test assertions to expect 'context used' in the footer display.
    • Adjusted snapshot expectations to reflect the new context usage display format.
  • packages/cli/src/ui/components/Footer.tsx
    • Removed the terminalWidth prop when rendering ContextUsageDisplay.
  • packages/cli/src/ui/components/snapshots/Footer.test.tsx.snap
    • Updated snapshots to reflect the new 'context used' display and 0% usage for full context.
  • packages/cli/src/ui/constants/tips.ts
    • Updated a tip message to refer to 'context compression threshold' instead of 'token usage'.
  • packages/cli/src/ui/hooks/useGeminiStream.test.tsx
    • Imported the theme object for color assertions.
    • Updated assertions for overflow warning messages to expect 'tokens left'.
    • Added new test cases to verify informational messages for ChatCompressed events, including succinct and detailed threshold messages.
  • packages/cli/src/ui/hooks/useGeminiStream.ts
    • Refactored handleChatCompressionEvent to provide a succinct 'Context compressed' warning and a detailed message showing the compression threshold as a decimal and percentage.
    • Updated the overflow warning message to be more concise, indicating 'tokens left'.
  • packages/cli/src/utils/settingsUtils.ts
    • Updated a comment for getEffectiveDefaultValue to reflect the new setting name.
    • Added logic to getDisplayValue to format compressionThreshold as a percentage and apply generic unit displays.
  • schemas/settings.schema.json
    • Updated the description for hideContextPercentage to refer to 'usage percentage'.
    • Renamed the title for compressionThreshold to 'Context Compression Threshold'.
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.

@github-actions
Copy link

github-actions bot commented Feb 23, 2026

Size Change: +1.27 kB (0%)

Total Size: 25.8 MB

Filename Size Change
./bundle/gemini.js 25.3 MB +1.27 kB (+0.01%)
ℹ️ View Unchanged
Filename Size
./bundle/node_modules/@google/gemini-cli-devtools/dist/client/main.js 221 kB
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/_client-assets.js 227 kB
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/index.js 11.5 kB
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/types.js 132 B
./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

Copy link
Contributor

@gemini-code-assist gemini-code-assist bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

The pull request successfully inverts the context window display to show usage percentage instead of remaining capacity. It also introduces dynamic coloring for warnings and errors, and simplifies related notifications. However, I identified a regression in responsive UI handling for narrow terminals, which impacts UI consistency, and a TypeScript type mismatch. Additionally, the use of magic numbers for layout should be addressed. These points should be resolved to maintain code quality and stability.

Comment on lines 12 to 18
export const ContextUsageDisplay = ({
promptTokenCount,
model,
terminalWidth,
}: {
promptTokenCount: number;
model: string;
terminalWidth: number;
}) => {
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

high

The removal of the terminalWidth prop and the conditional label logic is a regression in UI robustness. Previously, the component would abbreviate the label to just % when the terminal width was less than 100 characters to prevent layout overflow in the footer. Restoring this behavior is important for maintaining a clean UI on narrow terminal windows, aligning with the principle of maintaining UI consistency across components. Additionally, the magic number 100 used for the terminal width threshold should be replaced with a named constant to improve readability and maintainability. Furthermore, the model prop type should be updated to string | undefined to match the uiState.currentModel type passed by callers, preventing potential TypeScript errors.

Suggested change
export const ContextUsageDisplay = ({
promptTokenCount,
model,
terminalWidth,
}: {
promptTokenCount: number;
model: string;
terminalWidth: number;
}) => {
export const ContextUsageDisplay = ({
promptTokenCount,
model,
terminalWidth,
}: {
promptTokenCount: number;
model: string | undefined;
terminalWidth: number;
}) => {
References
  1. This rule emphasizes maintaining existing UI behavior across components and addressing larger UX changes holistically, rather than in isolated components. The comment highlights a regression in responsive UI that deviates from established behavior.
  2. This rule states that magic numbers, especially those for layout or padding, should be replaced with named constants to improve readability and maintainability. The comment identifies a hardcoded 100 for terminal width as a magic number.

textColor = theme.status.warning;
}

const label = '% context used';
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

high

Re-implement the conditional label logic to ensure the UI remains responsive on narrow terminals, maintaining consistency with existing UI behavior. The magic number 100 used for the terminal width threshold should be replaced with a named constant (e.g., MIN_TERMINAL_WIDTH_FOR_FULL_LABEL) to improve readability and maintainability.

Suggested change
const label = '% context used';
const label = terminalWidth < MIN_TERMINAL_WIDTH_FOR_FULL_LABEL ? '%' : '% context used';
References
  1. This rule emphasizes maintaining existing UI behavior across components and addressing larger UX changes holistically, rather than in isolated components. The comment highlights a regression in responsive UI that deviates from established behavior.
  2. This rule states that magic numbers, especially those for layout or padding, should be replaced with named constants to improve readability and maintainability. The comment identifies a hardcoded 100 for terminal width as a magic number.

Comment on lines 297 to 300
<ContextUsageDisplay
promptTokenCount={uiState.sessionStats.lastPromptTokenCount}
model={uiState.currentModel}
terminalWidth={uiState.terminalWidth}
/>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

high

Restore passing the terminalWidth prop to ContextUsageDisplay to support responsive label rendering, which aligns with maintaining consistency with existing UI behavior across components.

                  <ContextUsageDisplay
                    promptTokenCount={uiState.sessionStats.lastPromptTokenCount}
                    model={uiState.currentModel}
                    terminalWidth={uiState.terminalWidth}
                  />
References
  1. This rule emphasizes maintaining existing UI behavior across components and addressing larger UX changes holistically, rather than in isolated components. The comment highlights a regression in responsive UI that deviates from established behavior.

Comment on lines 149 to 152
<ContextUsageDisplay
promptTokenCount={promptTokenCount}
model={model}
terminalWidth={terminalWidth}
/>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

high

Restore passing the terminalWidth prop to ContextUsageDisplay to support responsive label rendering, which aligns with maintaining consistency with existing UI behavior across components.

                  <ContextUsageDisplay
                    promptTokenCount={promptTokenCount}
                    model={model}
                    terminalWidth={terminalWidth}
                  />
References
  1. This rule emphasizes maintaining existing UI behavior across components and addressing larger UX changes holistically, rather than in isolated components. The comment highlights a regression in responsive UI that deviates from established behavior.

Copy link
Contributor

@jacob314 jacob314 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Will follow up with a minor code review fixes pr.lgtm

@jacob314 jacob314 force-pushed the invert-context-used branch from 3c48a3c to 1af0be4 Compare March 3, 2026 09:10
@jacob314
Copy link
Contributor

jacob314 commented Mar 3, 2026

Pushed minor code review fixes to the pr.

@keithguerin keithguerin added this pull request to the merge queue Mar 3, 2026
Merged via the queue into main with commit 1e2afbb Mar 3, 2026
26 of 27 checks passed
@keithguerin keithguerin deleted the invert-context-used branch March 3, 2026 09:32
BryanBradfo pushed a commit to BryanBradfo/gemini-cli that referenced this pull request Mar 5, 2026
struckoff pushed a commit to struckoff/gemini-cli that referenced this pull request Mar 6, 2026
liamhelmer pushed a commit to badal-io/gemini-cli that referenced this pull request Mar 12, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Invert context window percentage display to show usage

2 participants