Skip to content

fix(usage): show a newer usage API percent in a session left idle - #767

Merged
sirmalloc merged 3 commits into
sirmalloc:mainfrom
eric-engberg:fix/idle-session-usage
Nov 6, 2026
Merged

sirmalloc merged 3 commits into
sirmalloc:mainfrom
eric-engberg:fix/idle-session-usage

Conversation

@eric-engberg

Copy link
Copy Markdown
Contributor

What

In a Claude Code session left idle, Block Usage, Weekly Usage and the per-model weekly widgets now catch up with usage from other sessions or devices. Once the session's last response is more than three minutes old, they show the usage API's percent when it's newer than the one Claude Code sent with that response.

Why

Claude Code sends the 5-hour and weekly percents with each of a session's API responses, and ccstatusline shows those over the usage API's. A session left idle keeps the percents from its last response. With refreshInterval set, its line redraws on that interval, but with the same numbers: while another session took the 5-hour block from 20% to 60%, an idle one still said 20% until its next prompt. On this machine, with refreshInterval: 30, idle sessions' lines looked frozen although Claude Code was rerunning the command every 30 seconds.

How

  • When it asks: for each 5-hour, weekly or per-model window that a widget on the line reads and the payload supplies, once the session's last response is older than the usage API cache's lifetime (three minutes). The time comes from the transcript's last assistant entry, the same one Block Forecast's history uses. A session with a recent response makes no request, and neither does a transcript with no response to date the percents by (a new one after /clear): the payload's percents stand.
  • Which percent wins: the usage API's, when the API sent it after that response (getUsageFetchedAtMs), for the same window (resets within a minute of each other), and no lower: usage never falls within a window, so a lower percent is another login's, after the credentials changed since the session's last response. Once the payload's window has reset, the API's current window wins.
  • Failures: the request is made like the other widgets' optional fetches: a failed or rate-limited fetch isn't an error on the line, and the payload's percents stay.
  • Cost: idle sessions read the usage API through its shared cache, so at most one request every three minutes across all sessions, as for the usage widgets that always fetch.
  • Forecast history: the 5-hour percent is dated by its source: the transcript's last response for the payload's, the API's fetch time once the API's replaced it.

Demo

Piped with fake data in a scratch HOME: an idle session whose last response, 20 minutes ago, came with 5h 20% and weekly 50%, while the usage API's cache, written just now, says 60% and 55%. Before, the line keeps the payload's 20% and 50%. After, it shows the API's 60% and 55%.

Powerline, before and after:

Before, Powerline

After, Powerline

Plain, before and after:

Before, Plain

After, Plain

Testing

  • New tests in usage-prefetch.test.ts (a scratch transcript dates the payload, a fake clock fixes now):
    • takes the API's newer percents once the last response is over three minutes old, asking only for the windows the line shows
    • keeps the payload's, without a request, while the last response is recent, and when the transcript has no response
    • keeps the payload's when the API's answer is older than the last response, when the API's percent is lower, and when the API answers another window the payload's hasn't reached
    • takes the API's new window once the payload's has reset
    • keeps the payload's percents, with no error, when the API can't answer
  • New test in session-usage-history.test.ts: the 5-hour percent is dated by the API's fetch time once it replaced the payload's.
  • Breaking each part of the rule on purpose (the time comparison, the same-window and no-lower checks, the reset case, the three-minute wait, asking only for shown windows, the suppressed error, the history's source) fails at least one test.
  • On current main: bun test 3700 pass, 0 fail (Bun 1.4.2). bun run lint: clean.
  • Built CLI under Bun 1.4.2 and Node 26.10.0, in a scratch HOME with fake credentials and a stub security: an idle session (last response 20 minutes ago) went from 5h: 20.0% Weekly: 50.0% to 5h: 60.0% Weekly: 55.0%; with a response a minute ago it kept 5h: 20.0% Weekly: 50.0%.

eric-engberg and others added 3 commits October 30, 2026 11:45
Claude Code sends the 5-hour and weekly percents with each of a session's
API responses, and the usage widgets show those over the usage API's. A
session left idle keeps the percents from its last response, so with
`refreshInterval` its line redraws with the same numbers while other
sessions or devices use up the limits.

Once the transcript's last response is more than three minutes old (the
usage cache's lifetime), the prefetch also asks the usage API for the windows
the line shows, through the shared cache and without surfacing errors. Its
percent wins when the API sent it after that response, for the same window
and no lower, or for the next window once the payload's has reset. The
forecast history dates the 5-hour percent by its source.
@sirmalloc
sirmalloc merged commit 08660d4 into sirmalloc:main Nov 6, 2026
3 checks passed
pcvelz added a commit to pcvelz/ccstatusline-usage that referenced this pull request Nov 13, 2026
Upstream: Extra Usage Today widget (sirmalloc#811), newer usage API percent in an idle session (sirmalloc#767), thinking-effort brackets and per-level colors (sirmalloc#777), 256-color grid in Edit Colors (sirmalloc#778), context bar thin line mode (sirmalloc#794), progress-bar widget consolidation (sirmalloc#810), Zed IDE link mode (sirmalloc#800), Check for Updates deadline and proxy fixes (sirmalloc#806), Configure Status Line before an install (sirmalloc#807), emoji and grapheme fixes (sirmalloc#808, sirmalloc#803, sirmalloc#790), Nerd Font icon width in Ghostty and kitty (sirmalloc#801), cache temp file leak fix (sirmalloc#783), plus TUI, timer and separator fixes.

Hand edits outside conflicts:
- src/tui/components/__tests__/InstallMenu.test.tsx: fork-rename (ccstatusline@ -> ccstatusline-usage@)
- src/utils/__tests__/hooks.test.ts: fork-rename (ccstatusline@ -> ccstatusline-usage@)
- src/tui/__tests__/App.test.ts: fork-rename; upstream's new menu and preview tests step over the fork's Off Hours row and pin cyan where the fork's Model default is ansi256:124
- src/tui/components/__tests__/ColorMenuPalette.test.tsx: fork deviation - Model default is ansi256:124
- src/utils/__tests__/global-package-manager.test.ts: fork deviation - fixture path uses the fork package name ccstatusline-usage
- src/utils/__tests__/migrations.test.ts: fork deviation - flexMode is a post-v1 key in the fork, the v1 sample uses globalBold
- src/utils/__tests__/usage-prefetch.test.ts: fork deviation - stub the provider gate (resolveProvider) in upstream's idle-session and daily-spend tests; the fork reads weekly usage from the API only
- src/utils/__tests__/update-checker.test.ts: lint import order
- src/utils/usage-prefetch.ts: lint - drop the unused fetchUsageData import
- src/widgets/WeeklyFableUsage.ts: compat fix - render through upstream's formatUsageBar (sirmalloc#810) so the line mode works; the inverted cursor follows the shared percent-widget rule
- src/widgets/__tests__/line-bar.test.ts: compat fix - fork WeeklyFableUsageWidget, weeklyFableUsage field and Fable label; block metrics stubbed so the inactive-block case does not read the real cache
- src/widgets/shared/__tests__/usage-display.test.ts: compat fix - the merged cycle has line mode after slider-only
- src/widgets/__tests__/ThinkingEffort.test.ts: keeps the fork's real-settings-file harness, ports upstream's sirmalloc#777 cases onto it
- bun.lock: upstream dependency updates, re-resolved by bun install
- docs/test-retirements.md: ledger for 7 tests upstream replaced (sirmalloc#781 tab as one space, sirmalloc#805 settings write failures, sirmalloc#800 Zed IDE link mode), each naming its replacing test
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.

2 participants