# Tokens and cost

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

How Agent HUD counts your agents' tokens, estimates their cost at list prices, and keeps 30 days of history on your Mac.

Updated 2026-10-28

Agent HUD reads the records your agents already keep and shows where the tokens went: which agents, models, sessions and turns used them, and what the same work would cost at list prices. Quotas tell you how much is left; token usage shows how it was spent.

## What is counted

Every call is split into five kinds that never overlap, so they add up to the whole call:

| Kind | What it holds |
| --- | --- |
| **Input** | New prompt tokens that did not go through the cache |
| **Output** | The reply, without its reasoning |
| **Reasoning** | Output spent thinking before the reply |
| **Cache write** | Prompt tokens written to the cache for later calls |
| **Cache read** | Prompt tokens read back from the cache |

- Many logs count reasoning inside output and cached tokens inside input. Agent HUD takes them out and counts each kind once.
- A response a log records more than once counts once.
- A session's tokens include the sub-agents it started. Totals across agents count each sub-agent's log once.
- **Cache hits** are the share of prompt tokens (input, cache writes and cache reads) read from the cache.

Cache reads are the context an agent reads back on every call, so they grow with the length of a session more than with the work done in it. For that reason the token charts start without them. When you compare two totals, compare them with the same kinds.

## Where you see it

- **Hover panel**: the last 24 hours of tokens, beside the quotas.
- **Statistics window**: open it with **Usage statistics** at the foot of the hover panel. It has two tabs, **Tokens** and **Sessions**.
- **Session page**: select a session in the Sessions tab or in the hover panel.
- **iPhone and Apple Watch**: token statistics, sessions and their tokens. See [iPhone](https://agenthud.app/docs/en/phone/iphone/).
- **Your agents**: the [built-in MCP server](https://agenthud.app/docs/en/mcp/) answers questions about usage, sessions and statistics from the same data.

{/* figure: the statistics window's Tokens tab, with the chart, the By agent cards and Recent usage, sample data */}

### The Tokens tab

| Control or section | What it shows |
| --- | --- |
| Range | **5 h**, **24 h**, **7 days** or **30 days** |
| Time bucket | 15 minutes, 30 minutes or 1 hour for 5 and 24 hours; 1 hour or 1 day for 7 days; 1 day for 30 days |
| Kinds | **Excl. cache reads** (the default), **All tokens**, or any mix of the five kinds |
| **Agents** and **Models** | Filter the chart to some agents or models |
| **By agent** | Each agent's tokens, share and estimated cost in the range, with its top models and sessions |
| **API balances** | Balances such as DeepSeek's, with the spend per day |
| **Recent usage** | Today, the last 7 days and the last 30 days, each with its cache hit rate and top models |
| **Activity heatmap · last 7 days** | The hours your agents worked |

### Session pages

A session's page shows its tokens with the sub-agents' part, its estimated cost, context fill and cache hits. For **Claude Code**, **Codex** and **DeepSeek Harness**, it also lists every turn with its new tokens, and each call in a turn with its model, its context and the tools it asked for. A call that had to send its context again is marked **Cache expired, context sent again**.

## Cost

The cost is an estimate: what the same calls would cost at the vendor's list price, marked **≈**. It is not a charge, and it is not what a subscription bills.

- Each kind is priced at its own rate, and each call at the price tier its prompt length reaches.
- **China or international list**: DeepSeek, GLM, Kimi (Moonshot), Qwen and MiMo publish both. Agent HUD uses the list of the platform the agent is configured for, from its endpoint or plan, and for DeepSeek from the currency of its balance. When it cannot tell, or an agent uses both platforms, it uses the international list.
- Yuan and dollar amounts are added up separately and never converted.
- A model with no list price adds nothing to the estimate, and the estimate's note names it.
- Calls through a relay use the relay's own price list when it has one, otherwise the vendor's list times a multiplier you set. Calls to a model server on your own computer are free.

### Correct a price

**Settings → Prices** lists every model your agents used in the last 30 days, with its tokens, its price per million tokens and where that price comes from: **List price**, **Relay's list**, **Multiplier**, **Your price** or **Local**. Select **Set price** to enter your own; costs follow at once. **Use the automatic price** goes back.

## History and time ranges

- **Token history** stays on your Mac for 30 days, in a local database. Older usage drops out a day at a time. When you first start Agent HUD, it reads the records already on your Mac, as far back as those 30 days.
- **The Sessions tab** lists sessions active in the last 7 days. **Day** groups them by the day they were last active; **Active** lists only sessions active in the last 24 hours or still running. You can filter by source and project path, and search by title, source, model or path.
- **Sub-agents** are not listed on their own; they open from the session that started them.
- **Archived or deleted sessions**: when you archive or delete a session in its agent, its tokens stay in your totals, and the session leaves every list.

## Where the numbers come from

Token counts come from the records each agent writes on your Mac: its logs or its local database, read without changing them. New usage appears as the agent writes it. Two agents differ:

- **Cursor** keeps no tokens on disk; its completion hook reports each generation's tokens, from Cursor 3.27 on, while [client hooks](https://agenthud.app/docs/en/agents/hooks/) are on.
- **Grok Bot**'s bots run on Cursor's servers, which report each bot's daily tokens.

A token total says nothing about how much quota is left: a quota percentage is the vendor's own reading of your plan. See [Quotas and balances](https://agenthud.app/docs/en/agents/quotas/).

---

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