feat: add API usage widgets (session, weekly, reset, context bar)

[pcvelz]

Summary

Adds four new widgets that display Claude Code API usage data, closing #94:

• session-usage: 5-hour session utilization with progress bar
• weekly-usage: 7-day utilization with progress bar
• reset-timer: countdown to next session reset
• context-bar: context window usage with progress bar (using context_window data from Claude Code stdin JSON)

Also enhances the existing ContextPercentage widget to use context_window data when transcript-based token metrics aren't available.

How it works

• Fetches from GET /api/oauth/usage using existing OAuth credentials (macOS Keychain + Linux ~/.claude/.credentials.json fallback)
• 180-second cache + 30-second rate limit lock to minimize API calls
• Widgets register in the standard widget registry — users add them via the TUI like any other widget
• No changes to default widget layout

Files changed

File	Change
src/widgets/ApiUsage.tsx	New — all 4 widget classes + credential reading + API fetch + caching
src/widgets/index.ts	Export new widgets
src/utils/widgets.ts	Register in widget registry
src/types/StatusJSON.ts	Add context_window schema for Claude Code's context data
src/widgets/ContextPercentage.ts	Enhanced to use context_window from stdin when available

Context

This was originally prototyped as a bash script and then implemented as native TypeScript widgets in a fork. This PR extracts just the widget code with no other changes.

Uses the same API approach as claude-pulse — same endpoint, same auth headers.

Test plan

• bun run build succeeds
• bun test passes
• Widgets appear in TUI widget list and can be added to lines
• Piped input renders session/weekly usage bars when credentials are available
• Shows [No credentials] gracefully when OAuth token is unavailable
• Cache file created at ~/.cache/ccstatusline-api.json after first API call
• Verify on Linux with ~/.claude/.credentials.json

[sirmalloc]

@pcvelz Thanks, I'll review this soon, travelling at the moment. How does this handle Windows and WSL? If they are unsupported, I'd like to still merge it, but with a system to gate it properly and have it only appear on supported OS's.

[zhil]

@sirmalloc can this be merged?

[liafonx]

Hi, this is quite a handy feature for Subscription users. Since the PR is still pending merge, would you mind adding a small custom feature that allows users to choose whether to hide or unhide the progress bar? For example, I like to keep the status line compact and only show the used percentage.
PS: Also request to support rawValue mode

[pcvelz]

@sirmalloc I've updated this PR with Windows support, based on @zac15987's working Windows snippet on issue #94.

I don't have access to a Windows machine myself, so I can't verify this with absolute certainty. That said, I'm fairly confident it works — I analyzed the differences between zac15987's working Windows script and our widget code, and the only deviation was process.env.HOME, which is undefined on Windows. Replaced it with os.homedir() which works cross-platform.

The rest of the code was already platform-agnostic:

• Credential reading uses fs.readFileSync (works on all platforms)
• API calls use Node's built-in https module (no curl/shell dependency)
• All paths use path.join() (handles Windows backslashes)
• macOS Keychain access is gated behind process.platform === 'darwin'

On Windows, credentials are read from ~/.claude/.credentials.json — same as Linux.

The fix is also published as v2.1.8 in the fork.

[sirmalloc]

@pcvelz I've got a Windows machine I can test on. I'll dig into reviewing this today.