Lagrange - Claude Code Usage

Know where you stand before the limit tells you.

A Windows desktop widget showing live session and weekly limits, token spend and context depth for Claude Code. It reads the same endpoint the /usage command reads, keeps the trail behind every number, and stays out of the way — compact, resizable, or folded into the tray.

claude code · usage · rate limits · session limit · weekly limit · token usage · context window · windows

---

Why

Claude Code knows its limits and will tell you — once you stop and ask it. A percentage that only exists inside a command you have to run is a percentage you find out about at the wrong moment, usually the one where a long task stops halfway.

This is that number, on screen, all the time, with the two things the command does not give you: how fast it is moving, and what it was spent on.

What you get

• Both limits, live. Session (five hours) and weekly, straight from GET /api/oauth/usage — the call Claude Code itself makes. Percentage spent, time until reset, and the wall-clock moment it refills.
• Where the number came from. Each limit carries the last hours as a trail, with the rate it is climbing (+4.2 %/h) and, when that matters, when it will be gone at this pace.
• What it went on. Tokens sent, received and read from cache inside each limit's window, read out of Claude Code's own transcripts.
• How full the conversation is. The context window of the session you are in right now, against the model's limit.
• Out of the way when you want it. Compact mode is a heads-up display you can resize — drag it short and wide and it becomes a strip along the top of a screen. The tray icon is itself a gauge.
• Nothing to sign in to. It reads Claude Code's own OAuth token, and only reads it: refreshing and rotating that token stays Claude Code's job, so this widget can never log you out of your editor.
• It notices when it stops working. A poller that stalls is replaced automatically, and figures older than a couple of intervals are labelled with their age instead of sitting there looking current. Restart widget in the tray menu covers whatever that misses.

Requirements

OS	Windows 10 or 11
Python	3.10+ with tkinter (only to run from source; the .exe needs nothing)
Claude Code	installed and signed in

No third-party packages. Standard library only.

Install

git clone https://github.com/volobado/claude-code-usage-widget.git
cd claude-code-usage-widget
pip install .
claude-usage            # the widget

Or build the standalone executable:

pip install pyinstaller
python scripts\build_exe.py     # dist\Claude Code Usage.exe — one file, ~12 MB

Use

📌	Keep on top (remembered)
▭ / ▤	Compact ↔ full view
▁	Hide to the tray
✕	Quit
drag an edge or the corner	Resize compact; short and wide becomes a strip
mouse wheel	Scroll, when there is more than fits
⟳	Refresh now (otherwise every two minutes)

Meters fill as the limit is spent — flame below 75 %, ember to 90 %, red past it. Both thresholds are settings.

Compact is the same readings at a glance, and it resizes: drag an edge or the corner, and dragging it short and wide turns it into a strip that lives along the top of a screen.

Command line

claude-usage                    open the widget
claude-usage status             limits, resets and tokens, once
claude-usage tokens             token totals (--by-day [N], --by-model)
claude-usage doctor [--json]    check every assumption

Where the figures come from

Limits come from GET https://api.anthropic.com/api/oauth/usage, with the OAuth token Claude Code stores in ~/.claude/.credentials.json and the anthropic-beta: oauth-2025-04-20 header the API requires. That is the same call behind /usage, so the numbers match to the percent.

The token is read, never written. Claude Code refreshes it on its own schedule and rotates the refresh token when it does; a widget racing it for that file is how somebody ends up signed out of their editor. If the token has expired and Claude Code has not run since, the widget says so and waits.

Tokens come from Claude Code's transcripts under ~/.claude/projects, where every assistant message records its own usage. They are read like a log — remember the byte offset reached in each file, resume there next time — so a first pass costs a few seconds and every pass after that costs nothing. Turns are keyed by message id, because a streamed response is written more than once.

Note that ↑ sent counts fresh input and cache writes: Claude Code sends almost everything as a cache write, and counting only input_tokens would report a few hundred tokens for an afternoon's work. Cache reads are kept separate — they are what the window reuses, not what it sent.

Context depth is the last turn's own accounting: what it read from cache, plus what it wrote into it, plus fresh input — exactly what was in front of the model on that turn.

Settings

~/.claude-usage/config.json, all optional:

key	default
refresh_seconds	120	How often to ask
warn_percent / danger_percent	75 / 90	Where meters turn amber and red
track_tokens	true	Read the transcripts at all
token_history_days	90	How much of the ledger to keep; 0 keeps everything
language	""	"ru" for Russian
effects	true	false stills the star field and the horizon pulse

Data lives in ~/.claude-usage/: window position, the readings trail, and the token ledger. All of it is counts and timestamps — nothing of what was said.

License

MIT — see LICENSE.

Not affiliated with Anthropic. "Claude" and "Claude Code" are trademarks of Anthropic PBC.