Improve /usage readability so users can understand quota consumption and reset timing

Open 💬 2 comments Opened Jun 23, 2026 by aliwatters

Problem

The current /usage output is hard to interpret when a user is trying to understand practical quota state: how much they have used, how close they are to a limit, and when quota exhaustion or resets will happen.

The current view emphasizes a long-range token activity heatmap plus summary counters. For users with frequent or heavy usage, the heatmap can saturate so that nearly every day looks like high activity. In that state, the chart communicates that usage happened frequently, but it does not answer the operational questions users need when they are close to a quota or considering whether to use a manual usage reset.

Impact

Users cannot tell:

  • how much quota remains in the current window;
  • which quota window is active, for example 5-hour, daily, weekly, or monthly;
  • when the current limit resets;
  • what a manual reset will do before spending one;
  • whether today's usage is normal or unusually high;
  • which tasks, sessions, repositories, or models are responsible for the usage.

The result is that /usage can show a large amount of visual data while still leaving the user unable to predict when limits will kick in.

Suggested behavior

Please add a readable summary above or alongside the heatmap that explains quota state in direct terms.

Useful fields would include:

  • current window name and duration;
  • used amount and remaining amount for the current quota window;
  • percentage consumed;
  • estimated time until reset, with an exact timestamp;
  • number of manual resets available;
  • clear explanation of what using a manual reset changes;
  • recent usage table for today, last 7 days, and last 30 days;
  • optional breakdown by model, repo/workspace, task/session, and command type;
  • whether the user is currently rate-limited or approaching a limit.

Acceptance criteria

  • /usage has a plain-language summary that can be understood without interpreting a heatmap.
  • The UI labels the active aggregation mode clearly: daily, weekly, or cumulative.
  • Saturated heatmaps still provide useful numeric context.
  • Users can determine when quotas will kick in and when they will reset.
  • Users can understand the effect of spending a usage reset before doing so.
  • The output works in terminal/plain-text environments, not only graphical clients.

Notes

The heatmap can still be useful as historical context, but it should not be the primary interface for quota decisions. The quota-related information should be presented as explicit numbers and timestamps first, with the heatmap as secondary context.

View original on GitHub ↗

This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗