How an agent surfaces its own consumption: token usage, dollar cost, rate-limit headroom. Three shapes — an inline footer indicator, a detailed breakdown card for billing/admin pages, and a rate-limit alert for soft warnings.
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.0142,184 tok3.2sclaude-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 usageApr 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 limitYou'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.