## When to use

The user is paying for the agent — directly (per-call billing) or indirectly (their company's plan). Surface usage where it informs a decision: at the bottom of a chat thread (inline), in the workspace billing tab (detailed), and as an inline alert when they're approaching a cap. Don't surface it inside every individual reply — the noise outweighs the signal.

## Inline indicator

Compact footer for the chat thread. Tokens + cost + duration. Uses `tag-ui` in a row; subtle text color so it doesn't compete with replies.

$0.014 2,184 tok 3.2s claude-opus-4-7

## Detailed breakdown card

Full breakdown for a billing or admin view. Stat tiles for the headline numbers; `description-list-ui` for the per-channel decomposition (input / output / cache).

Today's usage Apr 29 · across all sessions
Input tokens
  142,108 · $0.43
Output tokens
  38,294 · $1.72
Cache reads
  3,841 · $0.01
Cache writes
  1,267 · $0.25

## Rate-limit warning

Soft warning when the user is approaching a rate-limit. `alert-ui variant="warning"` with a `progress-ui` showing remaining headroom. Action button offers upgrade or wait-time.

Approaching token limit You've used 870k of your 1M daily token allowance. Resets at midnight UTC (in 4h 12m).

## Composition rules

- Inline = three signals max — cost, tokens, duration. Anything more belongs in the detailed view.
- Stats round consistently — kilo-tokens at 3 sig figs (184k, 1.42M); cost to 2 decimals ($0.01 floor).
- Rate-limit warning fires at 80%, not 100% — gives the user time to act. The 100% case is an error, not a warning.
- Trend deltas are vs the prior day — week-over-week deltas confuse users in active sessions. Use week comparison only on the billing tab.

## See also

- stat-ui — tile primitive used in detailed breakdown.
- alert-ui — the rate-limit warning surface.
- progress-ui — headroom indicator.
- tag-ui — inline indicator chips.