In, Out and Cache: how token usage is counted
Token counts only mean something if you know what went into them. Agent HUD keeps three dimensions that never overlap, so a number can be added up without counting anything twice.
Three dimensions that never overlap
Every request is recorded along three dimensions. They are additive and they never overlap, so In + Out + Cache is the whole of what a request cost, with nothing double counted.
| Dimension | Contains | Excludes |
|---|---|---|
| In | Fresh input: prompt tokens plus cache writes | Cache reads |
| Out | Output tokens; reasoning is already part of this count | — |
| Cache | Cache reads only | — |
Reasoning tokens are counted once
When a model thinks before it answers, those tokens are already inside the output count the provider returns. Agent HUD never adds them a second time, so a reasoning-heavy turn is not inflated relative to a plain one.
The default view is In + Out
Charts, the activity heat map, the model share and the session rows all follow whichever dimensions are selected. The default selection is fresh usage — In + Out — and switching to all adds cache reads on top.
A single session's token figure in the panel is the In + Out of that session. Records written before the cache dimension existed decode with zero cache reads rather than a guess.
Counted once, whatever the logs look like
- One API response counts once whatever the log layout happens to be.
- Copies of the same event from two files, or from two Macs, merge into a single record.
- Two genuinely separate requests that happen to carry identical counts are both kept.
How the bars are grouped
Bars are bucketed at 15 minutes, 30 minutes, 1 hour or 1 day, aligned to local quarter-hour, hour or calendar-day boundaries, inside the exact range being shown. A bucket with nothing in it keeps its position rather than collapsing, and counts stay whole numbers.
Tokens are not quota
The two are separate readings and one is never derived from the other. A provider that reports a quota window reports it directly; token counts come from the request logs. Agent HUD will not turn tokens into a quota percentage, and it will not fill in a missing quota from how many tokens you have spent.
Common questions
- Are reasoning or thinking tokens counted twice?
- No. Reasoning is already part of the output token count the provider returns, and Agent HUD never adds it again.
- Do cache reads count toward my usage?
- They are counted, but as their own dimension. The default view shows fresh usage — input plus output — and cache reads only appear when you switch to all dimensions. Cache writes are part of input, not of cache.
- If I run the same agent on two Macs, is my usage counted twice?
- No. Copies of one event arriving from two files or two machines merge into a single record. Two separate requests are kept separately even when their token counts are identical.
- Why don't my token totals line up with my quota percentage?
- They measure different things. Quota comes from the provider's own window readings; tokens come from the request logs. Neither is calculated from the other.
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