Skip to content

Add session-budget, weekly-budget, and peak-hours widgets#289

Open
actionk wants to merge 1 commit intosirmalloc:mainfrom
actionk:feature/budget-and-peak-widgets
Open

Add session-budget, weekly-budget, and peak-hours widgets#289
actionk wants to merge 1 commit intosirmalloc:mainfrom
actionk:feature/budget-and-peak-widgets

Conversation

@actionk
Copy link
Copy Markdown

@actionk actionk commented Apr 6, 2026

Summary

Three new widgets for tracking Claude Code usage budget and Anthropic peak hours:

  • session-budget — Shows 5-hour session usage with a surplus/deficit indicator relative to linear pacing. Example: 5h: 32% ↓34% means usage is 34% below the expected pace (you have headroom). means you're burning faster than expected.
  • weekly-budget — Same concept applied to the 7-day rolling window. Example: Week: 27% ↓9%
  • peak-hours — Shows whether Anthropic's peak hours are active (weekdays 5am–11am PT / 1pm–7pm GMT) with a countdown to the next toggle. Example: ⚡ Peak 3h20m or Off-peak 17h37m

How budget indicators work

Expected usage = (elapsed time / total window) × 100%
Difference = actual − expected

↓ = under budget (good — headroom remaining)
↑ = over budget (burning fast)

Widget types

Type Category Raw Value Colors
session-budget Usage
weekly-budget Usage
peak-hours Usage

Implementation details

  • Reuses existing resolveUsageWindowWithFallback and resolveWeeklyUsageWindow utilities for elapsed/remaining time calculation
  • Reuses formatRawOrLabeledValue, getUsageErrorMessage shared helpers
  • Peak hours uses Intl.DateTimeFormat with America/Los_Angeles timezone for reliable cross-locale PT conversion
  • All widgets follow the standard Widget interface pattern with preview mode support

Test plan

  • SessionBudget — 8 tests (preview, null data, errors, under/over budget arrows, raw value, clamping)
  • WeeklyBudget — 7 tests (preview, null data, errors, under/over budget, raw value)
  • PeakHours — 5 tests (preview, peak detection, off-peak detection, weekends, non-null guarantee)
  • All 20 tests pass
  • Lint clean (zero warnings)
  • No regressions in existing widget tests

Three new widgets for tracking usage budget and peak hours:

- session-budget: shows 5-hour usage with surplus/deficit indicator
  (↓ = under budget, ↑ = over budget based on elapsed time)
- weekly-budget: same concept for the 7-day rolling window
- peak-hours: shows whether Anthropic peak hours are active
  (weekdays 5am-11am PT) with countdown to next toggle

Includes full test suites for all three widgets.
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.

1 participant