From 648a1b0f369da43027fbdf420f177f5f9c56fff9 Mon Sep 17 00:00:00 2001 From: Eric Engberg Date: Fri, 9 Oct 2026 18:30:23 -0500 Subject: [PATCH 1/2] fix(usage): call Session Usage Block Usage, ending its "Session:" label clash Three widgets printed the label "Session: " and meant two different things by it. Session Clock and Session Name mean the Claude Code conversation; Session Usage meant the 5-hour usage window. On one line, "Session: 42% | Session: 1hr 5m" reads as two facts about the same session when they aren't. The 5-hour window already has a name here: Block Timer and Block Reset Timer call it the block. Session Usage becomes Block Usage, labeled "Block: ", with the description "Shows the current 5-hour block's usage percentage". Its type stays session-usage, so saved configs keep working, and anyone who prefers the old label can set "Session: " back with the label editor (e). The docs follow; past release notes keep the name they shipped with. --- docs/USAGE.md | 4 ++-- src/widgets/__tests__/SessionUsage.test.ts | 27 +++++++++++++++------- src/widgets/shared/usage-percent-widget.ts | 6 ++--- 3 files changed, 24 insertions(+), 13 deletions(-) diff --git a/docs/USAGE.md b/docs/USAGE.md index 7f8ac111a..885aade98 100644 --- a/docs/USAGE.md +++ b/docs/USAGE.md @@ -60,7 +60,7 @@ ccstatusline --version - **Input Speed** / **Output Speed** / **Total Speed** - Show session-average token throughput with an optional per-widget rolling window (`0-120` seconds; `0` = full-session average). - **Context Length** / **Context Window** / **Context %** / **Context % (usable)** / **Context Bar** - Show current context length, total context window size, used/remaining percentage, usable-window percentage, or a progress bar. The window size is taken from Claude Code's reported `context_window.context_window_size` when present, then from a model-name hint (e.g. a `[1m]` suffix), and finally from a fixed fallback. Set `CCSTATUSLINE_CONTEXT_SIZE_FALLBACK` to a positive integer to override that last-resort fallback (defaults to `200000`) — useful when an older Claude Code does not report the window size for a 1M-context model, so the bar would otherwise read against 200k. Immediately after `/compact`, transcript fallback uses the latest `compact_boundary.postTokens` value until a new main-chain turn reports the current size, so the widgets do not retain the pre-compaction context. - **Compaction Counter** - Show how many context compactions have been detected in the current session by scanning transcript compaction markers. It can render as icon plus number, text plus number, or number-only, and can hide while the count is zero. Two optional, independent per-item add-ons toggle extra detail: a trigger split (`↻ 3 (2 auto, 1 manual)`; a compaction whose trigger is missing or unrecognized is bucketed as `unknown`) and tokens reclaimed (`↻ 3 ↓887.0k`, each compaction's `preTokens - postTokens` floored at 0 and summed, shown only when greater than 0 — so very old transcripts predating the `postTokens` field display nothing). Its value selector can instead render the total count, one trigger count (`auto`, `manual`, or `unknown`), or reclaimed tokens as a standalone value; hide-when-zero applies to the selected value. -- **Session Usage** / **Weekly Usage** / **Weekly Sonnet Usage** / **Weekly Opus Usage** / **Weekly Fable Usage** / **Extra Usage Utilization** / **Extra Usage Remaining** / **Extra Usage Used** / **Extra Usage Daily Budget** / **Block Timer** / **Block Reset Timer** / **Weekly Reset Timer** - Show usage percentages, monthly pay-as-you-go overage usage, and current block/reset timing. Session and all-model weekly usage read the legacy flat API buckets when available and fall back per field to `session` and `weekly_all` entries in the newer `limits[]` response. The per-model widgets prefer `weekly_scoped` entries for Sonnet, Opus, and Fable, with legacy Sonnet/Opus buckets as fallbacks; Weekly Fable Usage renders nothing when the API reports no Fable quota. Session Usage, the weekly percentage widgets, and Extra Usage Utilization can show either used or remaining percentage in every display mode. Session and weekly usage bars can also show a time cursor. Extra usage widgets accept known extra-usage state as complete when an account has no monthly limit configured, avoid repeated refetches and stale `[Timeout]` output, and format amounts with the API-reported billing currency when available. On accounts with no plan limits (usage-based Enterprise plans), extra usage is all of the account's spend rather than overage beyond a plan; the label editor can change the Extra Usage widgets' `Overage` labels to read `Spend`. Before the first charge of the month the API reports no utilization, so Extra Usage Utilization works it out from the amount spent and the monthly limit. Extra Usage Daily Budget divides what's left of the monthly limit by the days left in the month, today included, optionally skipping future weekend days (today always counts). It requires a monthly limit and amount spent, and displays zero once the limit is exhausted. Days are UTC days, since monthly limits reset at 00:00 UTC on the 1st. Reset timers can show remaining time, progress, or exact reset date/time with timezone and locale controls; while reset data is still arriving at startup, they show a labeled loading placeholder instead of a transient API error. +- **Block Usage** / **Weekly Usage** / **Weekly Sonnet Usage** / **Weekly Opus Usage** / **Weekly Fable Usage** / **Extra Usage Utilization** / **Extra Usage Remaining** / **Extra Usage Used** / **Extra Usage Daily Budget** / **Block Timer** / **Block Reset Timer** / **Weekly Reset Timer** - Show usage percentages, monthly pay-as-you-go overage usage, and current block/reset timing. Block Usage and the all-model Weekly Usage read the legacy flat API buckets when available and fall back per field to `session` and `weekly_all` entries in the newer `limits[]` response. The per-model widgets prefer `weekly_scoped` entries for Sonnet, Opus, and Fable, with legacy Sonnet/Opus buckets as fallbacks; Weekly Fable Usage renders nothing when the API reports no Fable quota. Block Usage, the weekly percentage widgets, and Extra Usage Utilization can show either used or remaining percentage in every display mode. Block and weekly usage bars can also show a time cursor. Extra usage widgets accept known extra-usage state as complete when an account has no monthly limit configured, avoid repeated refetches and stale `[Timeout]` output, and format amounts with the API-reported billing currency when available. On accounts with no plan limits (usage-based Enterprise plans), extra usage is all of the account's spend rather than overage beyond a plan; the label editor can change the Extra Usage widgets' `Overage` labels to read `Spend`. Before the first charge of the month the API reports no utilization, so Extra Usage Utilization works it out from the amount spent and the monthly limit. Extra Usage Daily Budget divides what's left of the monthly limit by the days left in the month, today included, optionally skipping future weekend days (today always counts). It requires a monthly limit and amount spent, and displays zero once the limit is exhausted. Days are UTC days, since monthly limits reset at 00:00 UTC on the 1st. Reset timers can show remaining time, progress, or exact reset date/time with timezone and locale controls; while reset data is still arriving at startup, they show a labeled loading placeholder instead of a transient API error. An explicit per-model quota at 0% is shown even when its reset timestamp is still missing; the time cursor appears only once a usable window is available. Weekly Fable Usage uses the label `Weekly Fable:` and stays empty when the API reports no Fable quota. @@ -296,7 +296,7 @@ Widget-specific shortcuts: - **Git Conflicts**: `z` toggles how a visible conflict-free tree renders (`⚠0` or the clean glyph); `g` edits the conflict and clean glyphs - **Context % widgets**: `u` toggle used vs remaining display, `p` cycle percentage/short bar/short bar only - **Session Cost Rate**: `t` switch between active time (how long Claude spent working, the default) and clock time (the whole session) -- **Session Usage / Weekly Usage / Weekly Sonnet Usage / Weekly Opus Usage / Weekly Fable Usage / Extra Usage Utilization**: `p` cycle percentage/full bar/medium bar/short bar/short bar only and `u` switch between used and remaining percentage in every display mode. The editor row labels the current direction as `used` or `remaining`, while the `u` helper names the direction it will switch to. Session and weekly usage widgets use `t` to toggle the time cursor in bar modes. +- **Block Usage / Weekly Usage / Weekly Sonnet Usage / Weekly Opus Usage / Weekly Fable Usage / Extra Usage Utilization**: `p` cycle percentage/full bar/medium bar/short bar/short bar only and `u` switch between used and remaining percentage in every display mode. The editor row labels the current direction as `used` or `remaining`, while the `u` helper names the direction it will switch to. Block and weekly usage widgets use `t` to toggle the time cursor in bar modes. - **Extra Usage Daily Budget**: `w` toggle counting weekdays only (Saturday and Sunday, UTC, are skipped; today always counts) - **Block Timer**: `p` cycle time/full bar/short bar, `s` toggle compact time, `v` invert fill in progress mode - **Block Reset Timer**: `p` cycle time/full bar/short bar, `s` toggle compact time/date, `t` toggle exact reset date/time, `f` toggle 12/24-hour display in date mode, `z` edit timezone in date mode, `l` edit locale in date mode, `v` invert fill in progress mode diff --git a/src/widgets/__tests__/SessionUsage.test.ts b/src/widgets/__tests__/SessionUsage.test.ts index 2d3a59946..ccbf48de8 100644 --- a/src/widgets/__tests__/SessionUsage.test.ts +++ b/src/widgets/__tests__/SessionUsage.test.ts @@ -55,12 +55,12 @@ describe('SessionUsageWidget', () => { id: 'session', type: 'session-usage', metadata: { cursor: 'true', display: 'slider' } - }, context)).toBe('Session: ▓▓░░░│░░░░ 20.0%'); + }, context)).toBe('Block: ▓▓░░░│░░░░ 20.0%'); expect(render(widget, { id: 'session', type: 'session-usage', metadata: { cursor: 'true', display: 'slider-only' } - }, context)).toBe('Session: ▓▓░░░│░░░░'); + }, context)).toBe('Block: ▓▓░░░│░░░░'); }); it('applies the label override to every display mode', () => { @@ -68,7 +68,7 @@ describe('SessionUsageWidget', () => { const context: RenderContext = { usageData: { sessionUsage: 20 } }; const metadata = { label: '5h ' }; - expect(widget.getLabelPrefix()).toBe('Session: '); + expect(widget.getLabelPrefix()).toBe('Block: '); expect(render(widget, { id: 'session', type: 'session-usage', metadata }, context)).toBe('5h 20.0%'); expect(render(widget, { id: 'session', @@ -77,19 +77,30 @@ describe('SessionUsageWidget', () => { }, context)).toBe('5h ▓▓░░░░░░░░'); }); + // The widget was Session Usage, labeled "Session: ", which Session Clock and + // Session Name use for the conversation; the old label is an override away + it('is Block Usage, labeled "Block: ", and takes "Session: " back as an override', () => { + const widget = new SessionUsageWidget(); + const context: RenderContext = { usageData: { sessionUsage: 20 } }; + + expect(widget.getDisplayName()).toBe('Block Usage'); + expect(render(widget, { id: 'session', type: 'session-usage' }, context)).toBe('Block: 20.0%'); + expect(render(widget, { id: 'session', type: 'session-usage', metadata: { label: 'Session: ' } }, context)).toBe('Session: 20.0%'); + }); + runUsagePercentWidgetSuite({ baseItem: { id: 'session', type: 'session-usage' }, createWidget: () => new SessionUsageWidget(), errorMessageMock: usageErrorMessageMock, - expectedInvertedTime: 'Session: 76.5%', + expectedInvertedTime: 'Block: 76.5%', expectedModifierText: '(medium bar, remaining)', - expectedPreviewInvertedTime: 'Session: 80.0%', - expectedProgress: 'Session: [████████████░░░░] 76.5%', + expectedPreviewInvertedTime: 'Block: 80.0%', + expectedProgress: 'Block: [████████████░░░░] 76.5%', expectedRawInvertedTime: '76.5%', expectedRawProgress: '[████████░░░░░░░░░░░░░░░░░░░░░░░░] 23.4%', expectedRawTime: '23.4%', - expectedTime: 'Session: 23.4%', - expectedWholePercentTime: 'Session: 23%', + expectedTime: 'Block: 23.4%', + expectedWholePercentTime: 'Block: 23%', modifierItem: { id: 'session', type: 'session-usage', diff --git a/src/widgets/shared/usage-percent-widget.ts b/src/widgets/shared/usage-percent-widget.ts index 9dcf88ca5..a509a41f6 100644 --- a/src/widgets/shared/usage-percent-widget.ts +++ b/src/widgets/shared/usage-percent-widget.ts @@ -56,9 +56,9 @@ interface UsagePercentWidgetKindConfig { const USAGE_PERCENT_WIDGET_CONFIG: Record = { 'session': { - label: 'Session: ', - displayName: 'Session Usage', - description: 'Shows daily/session API usage percentage', + label: 'Block: ', + displayName: 'Block Usage', + description: 'Shows the current 5-hour block\'s usage percentage', previewPercent: 20, usageField: 'sessionUsage' }, From 150aab92267e409179a90ef240a92635549b3223 Mon Sep 17 00:00:00 2001 From: Eric Engberg Date: Fri, 9 Oct 2026 18:42:27 -0500 Subject: [PATCH 2/2] fix(usage): label Block Usage "5h: " rather than "Block: " "Block: " is already Block Timer's label, for the block's elapsed time ("Block: 3hr 45m"), so Block Usage beside it would print two "Block:" figures. Label it "5h: " instead, which says which window the percent is of and pairs with Weekly Usage's "Weekly: ". The name stays Block Usage, and a "Session: " override still sets the old label back. --- src/widgets/__tests__/SessionUsage.test.ts | 23 +++++++++++----------- src/widgets/shared/usage-percent-widget.ts | 2 +- 2 files changed, 13 insertions(+), 12 deletions(-) diff --git a/src/widgets/__tests__/SessionUsage.test.ts b/src/widgets/__tests__/SessionUsage.test.ts index ccbf48de8..54aa03bf0 100644 --- a/src/widgets/__tests__/SessionUsage.test.ts +++ b/src/widgets/__tests__/SessionUsage.test.ts @@ -55,12 +55,12 @@ describe('SessionUsageWidget', () => { id: 'session', type: 'session-usage', metadata: { cursor: 'true', display: 'slider' } - }, context)).toBe('Block: ▓▓░░░│░░░░ 20.0%'); + }, context)).toBe('5h: ▓▓░░░│░░░░ 20.0%'); expect(render(widget, { id: 'session', type: 'session-usage', metadata: { cursor: 'true', display: 'slider-only' } - }, context)).toBe('Block: ▓▓░░░│░░░░'); + }, context)).toBe('5h: ▓▓░░░│░░░░'); }); it('applies the label override to every display mode', () => { @@ -68,7 +68,7 @@ describe('SessionUsageWidget', () => { const context: RenderContext = { usageData: { sessionUsage: 20 } }; const metadata = { label: '5h ' }; - expect(widget.getLabelPrefix()).toBe('Block: '); + expect(widget.getLabelPrefix()).toBe('5h: '); expect(render(widget, { id: 'session', type: 'session-usage', metadata }, context)).toBe('5h 20.0%'); expect(render(widget, { id: 'session', @@ -78,13 +78,14 @@ describe('SessionUsageWidget', () => { }); // The widget was Session Usage, labeled "Session: ", which Session Clock and - // Session Name use for the conversation; the old label is an override away - it('is Block Usage, labeled "Block: ", and takes "Session: " back as an override', () => { + // Session Name use for the conversation; "Block: " is Block Timer's. The old + // label is an override away. + it('is Block Usage, labeled "5h: ", and takes "Session: " back as an override', () => { const widget = new SessionUsageWidget(); const context: RenderContext = { usageData: { sessionUsage: 20 } }; expect(widget.getDisplayName()).toBe('Block Usage'); - expect(render(widget, { id: 'session', type: 'session-usage' }, context)).toBe('Block: 20.0%'); + expect(render(widget, { id: 'session', type: 'session-usage' }, context)).toBe('5h: 20.0%'); expect(render(widget, { id: 'session', type: 'session-usage', metadata: { label: 'Session: ' } }, context)).toBe('Session: 20.0%'); }); @@ -92,15 +93,15 @@ describe('SessionUsageWidget', () => { baseItem: { id: 'session', type: 'session-usage' }, createWidget: () => new SessionUsageWidget(), errorMessageMock: usageErrorMessageMock, - expectedInvertedTime: 'Block: 76.5%', + expectedInvertedTime: '5h: 76.5%', expectedModifierText: '(medium bar, remaining)', - expectedPreviewInvertedTime: 'Block: 80.0%', - expectedProgress: 'Block: [████████████░░░░] 76.5%', + expectedPreviewInvertedTime: '5h: 80.0%', + expectedProgress: '5h: [████████████░░░░] 76.5%', expectedRawInvertedTime: '76.5%', expectedRawProgress: '[████████░░░░░░░░░░░░░░░░░░░░░░░░] 23.4%', expectedRawTime: '23.4%', - expectedTime: 'Block: 23.4%', - expectedWholePercentTime: 'Block: 23%', + expectedTime: '5h: 23.4%', + expectedWholePercentTime: '5h: 23%', modifierItem: { id: 'session', type: 'session-usage', diff --git a/src/widgets/shared/usage-percent-widget.ts b/src/widgets/shared/usage-percent-widget.ts index a509a41f6..dcb8b6d86 100644 --- a/src/widgets/shared/usage-percent-widget.ts +++ b/src/widgets/shared/usage-percent-widget.ts @@ -56,7 +56,7 @@ interface UsagePercentWidgetKindConfig { const USAGE_PERCENT_WIDGET_CONFIG: Record = { 'session': { - label: 'Block: ', + label: '5h: ', displayName: 'Block Usage', description: 'Shows the current 5-hour block\'s usage percentage', previewPercent: 20,