AI Usage

Finds cache breaks in a session -- turns where the prompt-cache prefix was not reused, so the context was re-written at cache-write prices instead of read back cheaply. A break is a spike in cache writes AND a drop in cache reads; a write spike alone (e.g. reading one large file) is not one. Each break lists the turn, token counts, likely cause (model or speed switch, idle past the 5-minute TTL, or an early-context change such as an edited CLAUDE.md), and its API-equivalent write premium from the pricing table. Also returns the overall cache hit rate and reads-per-write.

Token usage and cost per coding agent (Claude Code, OpenCode, Codex). Note that the two cost figures are not comparable as a single number: OpenCode reports actual charged cost, while the Claude Code and Codex figures are API-equivalent estimates (a subscription has $0 marginal cost per request).

What the tokens from a period would have cost at another model’s list rates, alongside what they actually cost. Use this for "would Sonnet have been cheaper than Opus for this". It re-prices the exact token counts that were recorded, grouped by client, model and speed so the fast-mode premium and the two different reasoning-token conventions are handled correctly. Also reports what the same tokens would have cost with NO prompt caching at all, per model -- which is the figure that says whether caching is paying for itself. IMPORTANT: the model scenarios are a counterfactual, not a saving — the same task on a different model generally takes a different number of turns with a different context on each, and nothing on disk can say what that would have been. Report it as such, keep every scenario labelled an estimate, and never subtract a scenario from the reported cost to claim a number.

Token usage and cost bucketed on the time axis, newest first. Use this for "how much did I use yesterday", for a trend over a period, or -- with grain "hour-of-day" -- for "when during the day do I burn tokens". Buckets with NO activity are included and flagged `zeroFilled`, because omitting them hides the gaps and makes an ordinary bucket look like a spike beside one weeks earlier. All buckets are local time, so they agree with the period filter rather than drifting by a timezone offset. Cost is labelled reported vs estimated per bucket.

Per-model token usage and cost, highest token count first. Use this to answer "which model consumed the most tokens". Cost is labelled reported vs estimated per model.

How much of the Claude Pro/Max 5-hour and weekly usage limits is used, as Claude Code itself last reported it, with when each window resets. Also the average pace within the window and the time it would reach 100% at that pace (a projection, labelled as one), and the tokens and API-equivalent cost of this machine's Claude Code turns since the window began. The percentages are recorded only while `ai-usage statusline` is configured as the Claude Code status line; without it they are reported as unavailable, never as 0%. Answers "how close am I to my limit" and "will I run out before it resets".

Per-project token usage and cost, highest token count first. A project is the working directory a turn ran in. Use this to answer "which repository is my spend going to". Turns whose project could not be resolved are grouped as (unknown) rather than dropped, and cost is labelled reported vs estimated per project.

Most recently active sessions with project path, client, model(s), duration, token breakdown and cost. Use the returned session id with session_usage for detail.

Usage for one session: client, model(s), duration, token breakdown and cost. Accepts a full session id or an unambiguous fragment of one. Subagent turns are reported separately from main-thread turns.

Token usage and cost cut by two or more dimensions at once -- project x day, model x day, client x day -- as one tidy row set. Use this for "which of my projects is getting more expensive", which the single-axis tools cannot answer: project_usage gives a total with no trend, and daily_usage narrowed to one project gives one series, so answering it otherwise means enumerating projects and issuing one call each. Combinations with no activity are absent rather than returned as zero rows. Cost stays labelled reported vs estimated per row and the two are never summed.

Where a period of usage went, how much of it did no new work, and what to change -- the first thing to run for "where are my tokens going" or "why do I hit my limit". Gives a verdict, the share of usage spent re-reading large contexts (every message re-sends the whole conversation) and rebuilding a lost prompt cache, the heaviest sessions by their own titles and git branches, usage per branch, and plain-language fixes. Shares are weighted by API-equivalent list price as a relative measure; on a subscription that figure is not money spent. Defaults to the last 7 days.

Total token usage and cost for a period, split by client (Claude Code, OpenCode, Codex). Tokens are broken out into input / output / cache-read / cache-write / reasoning, because cache tokens typically dwarf input and a single blended total is misleading. Reported cost (from OpenCode) and estimated cost (computed for Claude Code and Codex, which record none) are always listed separately and must not be summed. Also reports the cache hit rate and reads-per-write, which are what say whether the cache is paying for itself -- the raw cache counts alone cannot.