[FEATURE] `/usage` overloads the word "session": top "Session" block (this CLI run) vs "Current session" limit bar (5-hour window)

Open 💬 1 comment Opened Jun 13, 2026 by edgariscoding

Preflight Checklist

  • [x] I have searched existing requests and this feature hasn't been requested yet
  • [x] This is a single feature request (not multiple features)

Problem Statement

The /usage panel uses the word "session" to mean two different things within the same screen, which makes it ambiguous to read:

  1. The top "Session" block (Total cost, Total duration, Total code changes, Usage) refers to the current CLI session — this run of Claude Code.
  2. The "Current session" progress bar under the usage limits refers to a rolling ~5-hour, account-wide rate-limit window ("Resets 3:50pm").

These are unrelated scopes — one is "this CLI process," the other is "a block of time across my whole account" — but both are labeled "session." Reading top-to-bottom, it strongly implies the cost block and the limit bar describe the same thing. They don't.

A concrete giveaway, from a freshly-started CLI session:

  Session

  Total cost:            $0.0000
  Total duration (API):  0s
  Total duration (wall): 2s
  Total code changes:    0 lines added, 0 lines removed
  Usage:                 0 input, 0 output, 0 cache read, 0 cache write

  Current session
  ██                                                 4% used
  Resets 3:50pm (America/Chicago)

The top "Session" block reads $0.00 / 0 tokens (this CLI run just started), yet "Current session" reads 4% used — because the 5-hour window already includes earlier activity. Two different "sessions," stacked in the same view.

To be clear: nothing is broken and the numbers are correct. The problem is purely that one meaningful word is overloaded for two scopes in a single screen, which makes the panel harder to reason about than it needs to be.

Proposed Solution

Rename one of the two so "session" isn't reused for two scopes in the same view. Either direction works; the specific wording is secondary:

  • Option A — keep the limit bar as "Current session", and rename the top block to "This conversation" or "Current CLI session (this run)".
  • Option B — keep the top block as "Session", and rename the limit bar to "Current 5-hour limit window".

Even a one-line subtitle under each (e.g. "this Claude Code run" vs "rolling 5-hour account window") would resolve the ambiguity without a full rename.

Alternative Solutions

  • Today's workaround: mentally track which "session" is which, or restart the CLI and see which value resets to zero (the top block) versus which stays elevated (the limit bar).
  • Considered leaving it as-is, but the collision keeps biting people — see the related reports below where users couldn't tell which "session" had hit 100%.

Priority

Low - Nice to have

Feature Category

Interactive mode (TUI)

Use Case Example

  1. Midway through a long work session, I run /usage.
  2. The top shows Session → Total cost: $5.00 — I read that as "this session has cost $5."
  3. Just below, Current session 4% used — I naturally assume it refers to the same "$5 session."
  4. In reality they're different scopes: if I start a fresh claude session and rerun /usage, the top cost resets to $0.00 while "Current session %" stays where it was (it tracks the rolling 5-hour window, not the CLI run).
  5. With distinct labels, the relationship — "this CLI run" vs "a 5-hour account window" — would be obvious at a glance, with no need to experiment.

Additional Context

Related (not a duplicate): #54750 hits the same ambiguity from the diagnosis angle — it shows low local session cost but "Current session: 100% used," and explicitly asks for "a clearer distinction between 'this local Claude Code session' and 'global current 5-hour account/session limit'." That one is filed as a usage-accounting bug; this request is narrowly about the terminology overloading in the /usage view itself, independent of any accounting-accuracy question.

Precedent for wording/clarity reports: #37451 (/clear "misleading command semantics") and #35250 ("…is misleading").

_Claude Code version: 2.1.177 · macOS · iTerm2_

View original on GitHub ↗

This issue has 1 comment on GitHub. Read the full discussion on GitHub ↗