[FEATURE] `/usage` overloads the word "session": top "Session" block (this CLI run) vs "Current session" limit bar (5-hour window)
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:
- The top "Session" block (
Total cost,Total duration,Total code changes,Usage) refers to the current CLI session — this run of Claude Code. - 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
- Midway through a long work session, I run
/usage. - The top shows
Session → Total cost: $5.00— I read that as "this session has cost $5." - Just below,
Current session 4% used— I naturally assume it refers to the same "$5 session." - In reality they're different scopes: if I start a fresh
claudesession and rerun/usage, the top cost resets to$0.00while "Current session %" stays where it was (it tracks the rolling 5-hour window, not the CLI run). - 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_
This issue has 1 comment on GitHub. Read the full discussion on GitHub ↗