Does the percentage mean used or remaining?

Used, following Claude Code's own convention. A window at 90% has 10% left.

Why does Agent HUD show no quota for my Claude Code?

An API-key login or a third-party gateway has no plan limits to read, so no window appears and the reason is named beside the account. Local activity and token counts still work.

Does reading the quota cost anything?

No. It is a metadata request through the engine already on your Mac. No prompt is sent and nothing is billed.

Can I see this away from the Mac?

With Agent HUD Remote, which syncs one Mac's usage to the free iPhone, widget and Apple Watch apps.

Agent HUD · Guides

How to check your Claude Code usage

Claude Code meters several windows at once, so the useful question is which one is closest to full and when it comes back.

The windows

A session window covering five hours, a weekly window across all models, and a weekly window for each model family. Each carries its own reset time, and any one of them can be the one that stops you.

Where to see them

/usage inside a session. The authoritative answer, with each window's usage and reset. It is a snapshot you ask for, from inside one session.
Your Anthropic account page. Plan-level activity, in the browser, not live.
Your own status line. Claude Code hands it the current limits, so a line you write can print the session and weekly percentages and their resets, for that terminal.
A monitor on screen. Keeps the windows visible without a command, which is the only way to know before a window is empty rather than after.

What Agent HUD shows

The windows sit around the notch: one glow segment per window that has a reading, and a panel on hover with each window's percentage and reset time.

Percentages are the share used, following the convention of /usage. A window with no reading shows a dash rather than a zero, and quota is never estimated from token counts.

It reads the sessions and the sign-in already on your Mac. No API key, no account, and the reading sends no prompt and is not billed.

When it warns you

Warning at 70% used, critical at 90%. Four things notify once each: crossing 90%, reaching zero, a forecast that the window will run out before its reset, and a confirmed reset.

When a window runs out

Wait for the reset. The countdown says how long.
Use a lighter model. The heavier family has its own weekly window.
Move the work to another agent. Their allowances are separate.
Upgrade, if it is the same window every day.

Common questions

Does the percentage mean used or remaining?: Used, following Claude Code's own convention. A window at 90% has 10% left.
Why does Agent HUD show no quota for my Claude Code?: An API-key login or a third-party gateway has no plan limits to read, so no window appears and the reason is named beside the account. Local activity and token counts still work.
Does reading the quota cost anything?: No. It is a metadata request through the engine already on your Mac. No prompt is sent and nothing is billed.
Can I see this away from the Mac?: With Agent HUD Remote, which syncs one Mac's usage to the free iPhone, widget and Apple Watch apps.

Guides

Last updated: 2026-09-20 · The behaviour described here is documented in full, with the code it comes from, in Agent HUD Open. github.com/jazzenchen/agent-hud-open