Windows system-tray app that shows your Claude Code rate-limit usage at a glance.
A colored circle next to your clock with your session and weekly usage percentage. Green under 70, amber at 70+, red at 90+. Click for the full breakdown.
If you use Claude Code on a Pro or Max subscription, you have a 5-hour session window and a 7-day weekly cap. Hit either and you get cut off mid-refactor. Anthropic shows this in the CLI when you run /usage
, but only when you ask. This puts it in your tray so you can glance like any other dev metric.
Works across every IDE you use Claude Code in (VS Code, Cursor, plain terminal). The data comes from your own account via the same endpoint Claude Code itself uses.
- Windows 10 or 11
- Windows PowerShell 5.1 (built in) or PowerShell 7
- Claude Code installed and logged in (so
~/.claude/.credentials.json
exists)
No Node, no npm, no installer, no admin rights needed.
- Clone this repo to a permanent location:
git clone https://github.com/apexlocal-jz/claude-usage-tray.git "$env:USERPROFILE\.claude\bin\claude-usage-tray"
- Run the installer:
& "$env:USERPROFILE\.claude\bin\claude-usage-tray\install.ps1"
That adds a shortcut to your Startup folder and launches the tray immediately. You should see a colored circle with a number appear next to your clock within ~5 seconds.
If Windows blocks the script with cannot be loaded because running scripts is disabled on this system
, run this once and try again:
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
| Action | Result |
|---|---|
| Always visible | Colored % circle in the system tray |
| Hover | Compact tooltip: Claude S:54% W:6% So:1% |
| Left click | Modal with full breakdown and reset times |
| Right click | Refresh now / Details / Quit |
The icon color reflects the higher of your session and weekly utilization:
Green under 70%Amber at 70-89%Red at 90%+
If the icon shows !
(red) the tooltip explains the error. Usually it means your OAuth token expired (open Claude Code to refresh it) or the network is down.
Passive — just the icon next to your clock:
Hover — compact tooltip:
Left click — full breakdown with reset times:
& "$env:USERPROFILE\.claude\bin\claude-usage-tray\install.ps1" -Uninstall
That stops the running tray, removes the Startup-folder shortcut, and deletes the log directory at %LOCALAPPDATA%\claude-usage-tray
. To remove the script files too:
Remove-Item "$env:USERPROFILE\.claude\bin\claude-usage-tray" -Recurse -Force
No registry keys, no other files. Clean uninstall.
Every 5 minutes (with 0-60 second jitter), the script:
- Reads your OAuth token from
~/.claude/.credentials.json
(the file Claude Code itself maintains) - Calls
GET https://api.anthropic.com/api/oauth/usage
with that token - Parses
five_hour.utilization
,seven_day.utilization
,seven_day_sonnet.utilization
and theirresets_at
timestamps - Redraws the tray icon and tooltip
That's it. No background services, no extra processes, no telemetry. Single ~300-line PowerShell script using WinForms NotifyIcon
for the UI. The polling cadence matches Claude Code's own internal polling, with jitter added so we don't sync.
On 429 (rate limited), the script honors Retry-After
and backs off. On 401 (token expired), it shows a friendly error and waits for the next poll, by which time Claude Code has usually refreshed the token.
- Your OAuth token never leaves your machine except in the
Authorization: Bearer
header sent toapi.anthropic.com
over TLS 1.2. - No telemetry. The script makes exactly one HTTPS call (to Anthropic) per poll. There are no other network destinations.
- The log file (
%LOCALAPPDATA%\claude-usage-tray\tray.log
) records timestamps of errors and start/stop events. No tokens, no response bodies. - Response body is capped at 1 MB before parsing to prevent memory-exhaustion from a hostile or misconfigured response.
Retry-After
is capped at 1 hour so a bad 429 header can't lock the tray out indefinitely.- Source is ~320 lines of PowerShell with zero runtime dependencies. Audit it yourself in 10 minutes.
Threat model note: like Claude Code itself, the running script holds your OAuth token in memory during each poll (~5 ms per fetch, every 5 min). Any process running as the same Windows user can read that memory. This is inherent to all credential-using local utilities. If your threat model includes a hostile process running as your user, this tool is not a meaningful additional exposure on top of Claude Code itself, but it's worth knowing.
This is an independent, unofficial tool. Not affiliated with or endorsed by Anthropic.
It uses an undocumented Anthropic endpoint (/api/oauth/usage
) that powers Claude Code's own usage display. Anthropic may change or remove that endpoint at any time. If they do, this tool will break and that's a fixable bug, not a guarantee of service.
Use at your own risk. The MIT license disclaims all warranties.
The idea, the endpoint, and the color-threshold model come from Harsh1210/claude-usage-bar, a VS Code extension that does the same thing inside VS Code's status bar. If you live in VS Code, install that instead. This project is a Windows-tray equivalent for cross-IDE users.
MIT. See LICENSE.