Claude Session Widget

A tiny floating macOS desktop widget that shows your Claude Code 5-hour usage window: a live "resets in" countdown and how much you've used — the same numbers claude.ai shows, on your desktop at all times.

• Big countdown: time left in the current 5-hour window
• 31% used · resets 22:50 — real token utilisation + reset time
• Progress bar = % used (green through 50%, orange through 80%, red above 80%)
• Bottom arrow expands a matching weekly usage bar from the same cache
• A little Clawd mascot holding a stopwatch 🙂

It reads the exact figures from Anthropic's own rate-limit headers, so it matches claude.ai to the minute (including the weekly limit).

Requirements

• macOS (Apple Silicon or Intel)
• Xcode command line tools (xcode-select --install) — for swiftc
• A Claude Pro/Max subscription used via Claude Code (this tracks the Claude Code/subscription 5-hour window)

Install

unzip claude-session-widget.zip && cd claude-session-widget
./install.sh

That builds the widget from source, installs it to ~/Applications, and sets up two per-user launch agents that start at login. No sudo, nothing system-wide.

Prefer zero network calls? Install the widget only — it will estimate the window from your local transcripts instead (see "How it works"):

./install.sh --widget-only

Uninstall any time:

./uninstall.sh

How it works (and what to check before you trust it)

This tool touches your Claude credentials, so please read the ~250 lines of SessionWidget.swift and session_usage_poll.py before running it.

The 5-hour usage window is a server-side counter that spans every surface (Claude Code, claude.ai web, mobile). Your local Claude Code transcripts only see Claude Code, so reconstructing the window from them drifts whenever you also use the web/app. The only way to get the exact number is to read Anthropic's rate-limit headers — and those only come back on a real API call. So:

• session_usage_poll.py (a launch agent, every 10 minutes):
  • Reads your existing Claude Code OAuth token from the login keychain (the Claude Code-credentials item that Claude Code itself created — the first run may pop a one-time keychain "allow" prompt).
  • Makes one tiny 1-token /v1/messages call and reads the anthropic-ratelimit-unified-* response headers.
  • Writes them to ~/.claude/session-usage.json. That's it.
  • It only calls when you've used Claude Code in the last ~12 minutes, so an idle Mac never pings (a call after the window expired would itself open a new window). It clears ANTHROPIC_API_KEY so the call always bills to your subscription, never pay-as-you-go API credits. Cost is negligible.
• SessionWidget.swift just reads ~/.claude/session-usage.json and draws the card. With --widget-only (no poller) it instead estimates the window by chaining 5-hour blocks across your transcript timestamps and labels it est.

Nothing is sent anywhere except that one call to api.anthropic.com with your own token. No telemetry, no third-party servers, no analytics.

Files

Logs: /tmp/claude-session-widget.log, /tmp/claude-session-usage.log. Cache: ~/.claude/session-usage.json (inspect it any time).

Notes / FAQ

• Does it work without the poller? Yes — --widget-only gives a transcript estimate with no network calls. It can be off by up to ~1.5h if you also use claude.ai web/mobile, and it's flagged est.
• Will the token expire? Claude Code refreshes it in the keychain as you use it. If it's ever stale the poller just keeps the last known reset and the widget falls back to the estimate.
• Apple Silicon vs Intel? install.sh resolves your python3 automatically.
• It's ad-hoc code-signed locally at build time, so there's no "unidentified developer" gate — you built it yourself.

Free to use and modify for personal or non-commercial purposes (PolyForm NonCommercial 1.0.0 — see LICENSE). Built by a Claude Code user for Claude Code users — not affiliated with Anthropic.