feat(cli): Invert quota language to 'percent used'

[keithguerin]

Summary

Invert the language around quotas from "percent left" to "percent used" and introduce a refined visual progress indicator in the /stats command output.

Details

1. Quota Language Inversion

• Switched from "XX% usage remaining" to "XX% used" across all UI components (Footer, /stats, and pre-prompt alerts).
• Updated thresholds for warnings (80% used) and critical alerts (95% used).
• "100% used" state now displays as "Limit reached".

2. Visual Progress Indicator

• Added a 20-step visual bar (▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬) to the /stats table.

- **Left-Aligned:** The "Model usage" column is now left-aligned with consistent padding to ensure bars remain vertically synchronized. - **Refined Logic:** - Forced initial tick: Any usage > 0 (even 1 request) shows at least one tick. - Remaining hint: High usage < 100% shows at least one empty tick. - Solid state: 100% usage shows a full bar. - **Refined Styling:** - Filled steps use the primary text color (or status color if ≥ 80%). - Unfilled steps use the border color (`theme.border.default`) to match the input background.

3. Resilient Rendering

• Added safety checks to formatResetTime to handle missing or invalid reset dates.
• Components now render usage data even if reset times are unavailable (common in certain user tiers).
• Improved statistics title: Model Usage: [Model Name] (with bold label).

4. Technical Improvements

• Added getUsedStatusColor helper for "higher is worse" logic.
• Updated all relevant tests and snapshots (QuotaDisplay, StatsDisplay, Footer).

Related Issues

Closes #20098

How to Validate

1. Run npm test -w @google/gemini-cli -- src/ui/components/QuotaDisplay.test.tsx src/ui/components/StatsDisplay.test.tsx src/ui/components/Footer.test.tsx to verify UI logic.
2. Manually verify in the CLI footer and /stats output.

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

[gemini-code-assist]

Summary of Changes

Hello @keithguerin, 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 refactors the display of quota information across the CLI to present usage as 'percent used' rather than 'percent remaining'. This change improves consistency with other developer tools and UX guidelines. It involves updating calculation logic, display text, and color-coding thresholds in various UI components, including the footer and /stats command, ensuring that users clearly understand their resource consumption.

Highlights

• Quota Language Inversion: The language for displaying quotas has been inverted from 'percent left' to 'percent used' to align with updated UX writing guidance.
• Updated Thresholds: Warning thresholds are now set at 80% used, and critical alerts at 95% used.
• UI Reflection: These changes are reflected in the CLI footer, the /stats command output, and model-specific statistics.
• Column Renaming: The 'Usage remaining' column in the stats table has been renamed to 'Usage'.
• New Helper Function: A new getUsedStatusColor helper function was added to manage color logic where a higher percentage used indicates a worse status.

Changelog

• package-lock.json
  • Added strip-json-comments as a new dependency.
• packages/cli/src/ui/components/Footer.test.tsx
  • Adjusted the expected percentage in the footer test from 15% to 85% to reflect the 'percent used' logic.
• packages/cli/src/ui/components/QuotaDisplay.test.tsx
  • Renamed test cases to reflect 'usage < 80%' and 'used >= 80%' conditions.
  • Updated assertions for critical and warning thresholds to match the new 'percent used' calculation.
• packages/cli/src/ui/components/QuotaDisplay.tsx
  • Replaced getStatusColor with getUsedStatusColor and updated threshold constants.
  • Changed percentage calculation to usedPercentage (100 - remaining).
  • Modified displayed text from 'usage remaining' to 'used'.
• packages/cli/src/ui/components/QuotaStatsInfo.tsx
  • Replaced getStatusColor with getUsedStatusColor and updated threshold constants.
  • Changed percentage calculation to usedPercentage (100 - remaining).
  • Modified displayed text from 'usage remaining' to 'used'.
• packages/cli/src/ui/components/StatsDisplay.test.tsx
  • Updated assertions to check for 'Usage' instead of 'Usage remaining'.
  • Modified expected percentage values and added 'used' suffix to match the new display format.
• packages/cli/src/ui/components/StatsDisplay.tsx
  • Renamed the table header from 'Usage remaining' to 'Usage'.
  • Updated the calculation for remainingFraction to display 'percent used'.
• packages/cli/src/ui/components/snapshots/Footer.test.tsx.snap
  • Updated the snapshot to reflect the new 'percent used' value in the footer.
• packages/cli/src/ui/components/snapshots/QuotaDisplay.test.tsx.snap
  • Updated snapshots for QuotaDisplay to show 'percent used' values and new test case names.
• packages/cli/src/ui/components/snapshots/StatsDisplay.test.tsx.snap
  • Updated snapshots for StatsDisplay to reflect the 'Usage' column name and 'percent used' values.
• packages/cli/src/ui/utils/displayUtils.ts
  • Added QUOTA_USED_WARNING_THRESHOLD and QUOTA_USED_CRITICAL_THRESHOLD constants.
  • Implemented getUsedStatusColor to determine status color based on 'used' percentage (higher is worse).

Activity

• Tests were added/updated to cover the new quota display logic.
• The changes were validated on MacOS using npm run.

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]

Size Change: +5.18 kB (+0.02%)

Total Size: 26 MB

Filename	Size	Change
./bundle/gemini.js	25.5 MB	+5.18 kB (+0.02%)

ℹ️ 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}

[gemini-code-assist]

Code Review

This pull request successfully refactors the quota display logic to show 'percent used' instead of 'percent remaining', which is a clear UX improvement. The changes are consistently applied across UI components, tests, and snapshots. I have one point of feedback regarding an unrelated dependency change that should be addressed to keep the pull request focused.

[keithguerin]

Addressed the concern about the strip-json-comments dependency. This was a phantom diff caused by an out-of-sync branch and has been resolved after rebasing on the latest main. The PR now only contains the quota language inversion changes.

[jacob314]

Great work on this PR! The inversion to "percent used" and the new visual progress bar look really solid. I also appreciate the thorough test updates.

I have one minor piece of feedback regarding the layout on smaller terminals:

Terminal Truncation Risk (StatsDisplay.tsx)
The usageLimitWidth has been increased to 85, bringing the total row width to 117 (25 for name + 7 for requests + 85 for quota). On standard 80-column terminals, the wrap="truncate-end" on the Text component will likely cut off the end of the verbose reset time string (e.g., 90% used (Limit resets in 1 hour 30 minutes at 9:30 PM PST)), making it invisible.

Suggestion: Consider using a more compact format for the reset time in this table view (e.g., resets in 1h 30m), or dropping the absolute time portion so users on narrower terminals can still see when their limits reset.

[sehoon38]

I think these are no longer used? if so we could clean these up

[jacob314]

This looks beautiful but requires too large a terminal window.We either need to move the limit reset times to a separate
line or hide the visualization of quota used when the terminal width is less than 117 or so.
Alternately would suggest tweaking the time left to (Limit resets in 23 hours) from the overly verbose (Limit resets in 23 hours 38 minutes and 5 seconds)
Would also suggest making the usage visualization shrink to perhaps a 5 chars wide when the terminal is too narrow to fit the full width.

[sehoon38]

I've addressed the feedback regarding verbosity and terminal width. The reset time is now more concise (e.g., '1h 5m') and the stats table is responsive to terminal width, shrinking or hiding elements as needed. Tests and snapshots have been updated and are passing.

still reviewing

[sehoon38]

we should add some tests for this

[sehoon38]

I was hoping if there's something we could use for the greater height but still doesn't overlap with the next line, and found this character 'Lower Seven Eighths block' ▇ that leaves 1/8 gap.

[jacob314]

[sehoon38]

LGTM