# Quotas and balances

[Agent HUD Docs](https://agenthud.app/docs/en/)

How Agent HUD reads each vendor's quota windows and balances, forecasts the burn rate, and alerts you before a window runs out.

Updated 2026-10-28

Agent HUD keeps every quota your agents' vendors report at the edge of your screen: how much of each window is used, when it resets, how fast it is going this cycle, and whether that pace runs it out first. Balances, such as DeepSeek's, show as money with the spend per day.

![The hover panel: Claude's and OpenAI's quota windows with the share used and the reset time, and a DeepSeek balance](https://agenthud.app/docs/images/hud/panel.dark.webp)

## What a window is

A **window** is one allowance the vendor meters over a period, with its own name, length and reset time: a five-hour session window, a weekly limit, a monthly total. Each row in the panel is one window exactly as the vendor reports it. Agent HUD does not assume what your plan includes.

- Windows are never added together. A weekly Claude limit and a five-hour Codex limit run on different clocks, and any one of them can be the one that stops you.
- Quota belongs to the account. Two programs on one sign-in, such as the Codex app and the Codex CLI, show one set of windows. Two Macs signed in to the same account read the same windows from the vendor.
- Tokens are never turned into quota, and a missing quota is never worked out from token counts.

## Each vendor's windows

In the panel, quota blocks are named by vendor: Claude Code's windows are under **Claude**, Codex's under **OpenAI**. Where space is tight, a row may show a shorter name, such as **Weekly**.

| Agent | Windows, as the app names them |
| --- | --- |
| Claude Code | **Current session** (five hours), **Weekly limit · All models**, and a weekly limit for each model family your plan limits, such as **Weekly limit · Opus** |
| Codex | Named by length, such as **5h limit** and **Weekly limit**. Any other limit Codex reports shows under its own name. The earned resets your account has available are counted beside them |
| Cursor | **Included usage**, **Cursor Models**, **Other Models**, **Individual spending limit**, **Pooled usage** and **On-demand usage**, as far as your plan reports them, with the reset Cursor gives |
| GitHub Copilot CLI | **Premium requests**, **AI credits**, **Chat messages** and **Code completions**: the ones metered on your plan, each with its reset date |
| Antigravity | One row per model group and window, such as **Gemini Models** or **Claude and GPT models** |
| Grok Bot | **Weekly usage limit**, or **Trial usage limit** during a trial, and **Extra usage** when a limit is set for it |
| Kimi | **5-hour quota**, **Weekly quota** and **Monthly total quota**, as your Kimi Code plan reports them |
| OpenCode | The OpenCode Go plan's **5-hour limit**, **Weekly limit** and **Monthly limit** |
| GLM Coding Plan | **5-hour credits** and **Weekly credits**, or **5-hour limit** and **Weekly limit** on older plans, and **MCP usage** when GLM reports it |
| Devin CLI | **Daily limit** and **Weekly limit** |
| DeepSeek Harness | A balance, not a window |
| Pi | The plans it runs on: a ChatGPT sign-in under Codex, a GLM key under GLM |
| WorkBuddy | A model's plan limit, only after WorkBuddy records reaching it, until the reset it gave |

The agents with no quota column in [Supported agents](https://agenthud.app/docs/en/agents/supported/) report none; Agent HUD shows their tokens and sessions only.

## Reading a row

Each row shows the share of the window used and the time it resets.

- **Used or left**: by default the percentage is the share used. To show the share left instead, open **Settings → General → Usage display** and set **Quota percentage** to **Remaining (100% → 0%)**. An 82% used window then reads 18%. Colours, burn rate and alerts always work from the share used.
- **`--`**: no reading has arrived for this window yet, or the vendor does not report it for your account. It never means zero.
- **Pending update**: the reset time has passed, but no new reading has confirmed the reset. The row keeps its last reading until one does.
- **Stale**: the last read failed, so the row keeps the last reading and marks it out of date: "Last quota reading is stale; refresh this account."

A reset counts once a new reading moves the reset time forward, or shows the window back at zero after it had been at least 5 points higher.

To hide a window or change the order of rows, see [Glow and panel](https://agenthud.app/docs/en/hud/glow-and-panel/).

## Burn rate and forecast

The **burn rate** is the share of a window used per hour, measured from the readings of its current cycle. Switch a block's rows to it with the flame button beside the block. Each row then shows:

- the rate, such as **10.0%/h**;
- the day and time the window runs out, when that pace empties it before the reset;
- otherwise the share you will have used by the reset, such as **62% by reset**.

A forecast needs readings that span at least 15 minutes of the current cycle, or one hour for a window of a day or longer, such as a weekly limit. Until then the row says **Sampling**, and after each reset, **Resampling**.

For example: with 40% left and a burn rate of 10% an hour, the window lasts about four hours if the pace holds. If it resets in three hours, it lasts; if it resets in six, it runs out first.

The burn rate measures quota, not tokens per hour or cost.

## Colours and alerts

The glow and each row take their colour from the share used. The levels are fixed, so a reading has the same colour on the Mac, iPhone and Apple Watch:

| Share used | Colour |
| --- | --- |
| Under 70% | Green |
| 70% and above | Yellow |
| 90% and above | Red |

A window counts as used up when 0.5% or less is left.

Alerts appear on the HUD itself, never as macOS notifications. Agent HUD alerts you:

1. **Once when a window is at risk**: the forecast says it runs out before its reset, or it crosses 90%. The alert reads "At the recent burn rate, this window may run out before it resets." or "Usage has reached the critical threshold."
2. **When a window is used up**: "This window is empty. Waiting for reset."
3. **When a new reading confirms a reset**: "This quota window has reset." If the same account has other windows still used up, the alert names them.
4. **When Codex adds an earned reset** to your account: "A usage reset was added to this account."

The first reading after Agent HUD starts only sets a baseline, and a reading more than 30 minutes old raises nothing, so restarting the app never repeats an alert. With Agent HUD Remote, the alerts for crossing 90%, a used-up window, a confirmed reset and a new earned reset also reach iPhone and Apple Watch; a forecast-only warning stays on the HUD.

## Balances

An agent billed from a balance shows money, not a percentage.

- **DeepSeek Harness**: the DeepSeek API balance, in its own currency, with the spend per day and the day it runs out at that pace. The spend is an estimate at DeepSeek's list price from the calls Harness recorded on this Mac. The balance turns yellow at 10 CNY or 2 USD and below, and red at zero or when DeepSeek refuses calls.
- **Relays**: when your agents go through a relay, you can switch it on in **Settings → Relays** to read what it has left. Nothing is sent to a relay until you switch it on.

Each currency stays as it is; amounts are never converted.

## More than one account

Each account shows under its vendor with its own label and windows. The same account seen twice, such as one email reported by two Antigravity CLIs, counts once.

- **Claude Code** and most other agents: the account the agent is signed in to on this Mac.
- **Codex**: the same email in two workspaces stays two accounts. A ChatGPT sign-in in Pi that matches a Codex account counts once.
- **GLM Coding Plan**: each key is its own plan, even when two keys belong to one account.

### Add Codex accounts

Sign in to each extra account with Codex, each under its own `CODEX_HOME` folder.

Open **Settings → Agents → Codex** and find **Additional Codex accounts**.

Add each folder, one per line, as an absolute path or starting with `~/`, then select **Save accounts**.

Your default account stays included. The extra accounts add their limits, not their sessions, and Agent HUD reads them one at a time. A failed folder shows a notice while the others keep reading. Clear the list to return to the default account only.

### Add Antigravity CLI accounts

Open **Settings → Agents → Antigravity** and find **Antigravity CLI accounts**.

Add the path of each CLI's `settings.json`, one per line, or select **Add default configuration**.

Select **Connect accounts**, then start or restart each CLI.

Connecting adds a local quota callback beside the CLI's status line and keeps your status line as it was. Accounts appear as you use them, including after you switch accounts in the CLI. A reading older than five minutes is marked stale until the CLI reports again. To restore a CLI's original status line, remove its path and select **Connect accounts** again.

## Signed out, or a read that fails

An agent that is missing, signed out or failing never hides the others.

- **Signed out**: the agent's quota rows go away, and its block says why and how to sign back in, for example "Claude Code is signed out. Run claude to sign in again and the quota returns" or "Codex is not signed in. Run codex login with ChatGPT to read its quota".
- **No plan limits**: an API key, a third-party platform or a custom model provider has no plan to read, and the block says so, for example "No plan limits for this login (API key or third-party platform)".
- **A failed read**: the last reading stays, marked stale, and Agent HUD tries again.

In every case the agent's tokens and sessions keep counting from the records on your Mac. Accounts are read one at a time, and no read sends a message to a model.

---

简体中文: https://agenthud.app/docs/zh/agents/quotas/