# Usage2

> For Claude Code SUBSCRIPTION users (Pro / Max 5x / Max 20x) — give the agent visibility into its own token consumption with API-equivalent dollar cost, % of session/week quota, and per-subagent attribution. Reads Claude Code's per-message `usage` blocks from the session transcript JSONL. Captures the built-in `/usage` panel via tmux for rolling 5h/7d/Sonnet-only quota percentages. Includes a passive calibration that learns your tier's tokens-per-percent from real samples. Use when the user says "/usage2", "how many tokens", "token cost", "compare token usage", "am I being efficient", "what's my quota", "how close to the limit", "subagent cost", "which subagent burned the most", or whenever the agent needs to reason about session/week budget, model efficiency, or A/B token comparisons.

- Skill: `loringtonian/usage2` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add loringtonian/usage2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/loringtonian/usage2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: Loringtonian (https://skillmd.com/u/loringtonian)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/loringtonian/usage2

---


# /usage2

For **Claude subscription users** (Pro / Max 5x / Max 20x). The dollar figures are *API-equivalent* (what you would have paid on metered API). You actually pay the flat subscription fee.

**Why this exists:** so the agent can *self-assess its own token efficiency, plan effective session usage, and make token spend predictable* — not just watch a number climb. With this skill the agent can answer "how much session budget is left", "what will this action cost", and "is approach A cheaper than approach B" without the user babysitting a panel.

Three capabilities in one skill:

1. **Token meter** (~10ms) — reads the session transcript JSONL and reports authoritative per-action token consumption, API-equivalent dollar cost, cache breakdown, per-subagent attribution.
2. **Quota panel** (~12s, cached for 10 min) — captures Claude Code's built-in `/usage` panel via tmux for rolling 5h / 7d / Sonnet-only meters with reset times.
3. **Calibration** — learns your tier's tokens-per-percent passively from each `quota` capture. After 2+ samples you can estimate "this 50K-token action will be ~X% of my session."

## Token budgets (Max 20x, measured 2026-05-19)

Empirical priors so the agent can reason about budget immediately — before any calibration. One 5-hour session window at 100% panel saturation, single-model strategy:

| Model      | Session cap | $/pp   | output tokens/pp | cache_read tokens/pp |
|------------|-------------|--------|------------------|----------------------|
| Haiku 4.5  | ~$44        | $0.443 | 56,190           | 1,122,644            |
| Sonnet 4.6 | ~$46        | $0.464 | 23,067           | 219,383              |
| Opus 4.7   | ~$50        | $0.499 | 11,817           | 131,527              |

`pp` = 1 percentage-point of the `/usage` session window. The panel is approximately model-neutral — $/pp differs by at most ~13% across models. Per-call cost (2000-word generation over a ~62K-token cached prefix): cold $0.10 / $0.21 / $0.54, hot $0.02 / $0.08 / $0.24 for Haiku / Sonnet / Opus.

These are priors (Max 20x measured directly; Pro and Max 5x are linearly scaled, untested) and hold until Anthropic changes limits. `meter.py budget` prints the full per-bucket table; `meter.py sample` twice calibrates against your own account. Full methodology: `research/per_model_cost_v5.md`.

## First-time setup

```bash
python3 ${CLAUDE_SKILL_DIR}/meter.py tier max20x   # or pro / max5x
python3 ${CLAUDE_SKILL_DIR}/meter.py sample        # first calibration sample
```

(Sample again ~15 min later to derive slopes.)

## Invocation

```bash
python3 ${CLAUDE_SKILL_DIR}/meter.py [mode] [args]
```

Modes:

| Mode                | Purpose                                                          | Cost   |
|---------------------|------------------------------------------------------------------|--------|
| `summary` (default) | Tokens + $ + % session + % week + calibration + signals          | ~12s\* |
| `quick`             | One-line: tokens · $ · cache% · session% · week%                 | ~10ms  |
| `agents`            | Per-subagent attribution: agentType, $, prompt preview           | ~10ms  |
| `mark <name>` `[--quota]` | Save a checkpoint, optionally with a quota snapshot        | ~10ms / ~12s |
| `since <name>`      | Token + $ + quota delta since checkpoint                         | ~10ms  |
| `marks`             | List saved checkpoints                                           | ~1ms   |
| `drop <name>`       | Delete a checkpoint                                              | ~1ms   |
| `raw`               | JSON dump of everything (for downstream tools)                   | ~10ms  |
| `quota`             | Force-refresh quota panel + show parsed result                   | ~12s   |
| `sample`            | Take a calibration sample (forces quota capture)                 | ~12s   |
| `calibrate`         | Show calibration history + derived tokens-per-percent estimates  | ~1ms   |
| `calibrate-account-scope` | Consecutive-pair $/pp slopes from short-interval samples   | ~1ms   |
| `estimate` `--model <m> --tokens <N>` | $ + est. session/week % impact for a planned action | ~1ms   |
| `budget`            | Empirical session token budget for your tier (caps, $/pp, tokens/pp) | ~1ms   |
| `reset-calibration` | Archive all reports to `reports_archive/<timestamp>/`            | ~10ms  |
| `tier [<t>]`        | Show or set subscription tier (pro / max5x / max20x)             | ~1ms   |

\* The cached quota result is reused for 10 minutes, so consecutive `summary` calls within that window are ~10ms.

## A/B comparison workflow

For settling questions like *"native-resolution image vision request vs resize to 1024×1024 — which costs fewer tokens?"*:

```bash
python3 meter.py mark approach-A --quota
# ... agent does approach A ...
python3 meter.py since approach-A

python3 meter.py mark approach-B --quota
# ... agent does approach B ...
python3 meter.py since approach-B
```

`since` reports tokens + dollars + percentage-point delta on each quota window.

## Output anatomy

A full `summary` reports:

- **Main thread** — turns, tool calls, input/output/cache split, per-model breakdown, API-equivalent dollars, avg-per-turn
- **Subagents** — grouped by `agentType`, with assumed model (default mapping: Explore→Haiku, general-purpose→Sonnet), per-spawn dollars and prompt preview
- **Grand total** — tokens + dollars
- **Tier context** — "this session = N days of your subscription fee in API-equivalent value"
- **Rolling quota windows** — session 5h, week (all models), week (Sonnet only) with reset times, age of the cached reading
- **Calibration** — once you have ≥2 samples: tokens-per-percent and estimated full-window capacity
- **Efficiency signals** — cache hit ratio (good ≥80%, churning <50%), output/input ratio, per-turn growth trend

## Autonomous self-throttling

Tell the agent at the start of a long autonomous run:

> Every 10 minutes, run `/usage2 quick`. If session reaches 75% or grand-total grows by more than 500K tokens since the last check, pause and report. If cache hit ratio drops below 60%, also pause — something is invalidating the cache.

`quick` is ~10ms (uses cached quota). It's free to poll.

## How calibration works

Each time you run `sample` (or any mode that refreshes the quota panel), the meter records:

- Current %s for the three quota windows
- The trailing 5h and 7d token totals (weighted by API-rate ratios into "input-equivalent" units)

From ≥2 samples, the meter computes tokens-per-percent for each window. With this you can:

- See your tier's effective rolling-window capacity
- Estimate the % impact of a planned action before doing it
- Spot anomalies (a sudden jump in % with little token usage usually means the panel reset)

Anthropic doesn't publish exact per-tier token caps — calibration is how `usage2` learns them empirically.

## Caveats

- **The current in-flight turn isn't yet in the JSONL.** Claude Code writes assistant messages after the turn completes. The meter is always one turn behind.
- **Subagents are aggregated, not per-step.** `toolUseResult.totalTokens` gives the full cost of a subagent dispatch, but the parent transcript doesn't include the subagent's internal turn-by-turn detail. Subagent costs assume a model per `agentType` (see `AGENT_TYPE_MODEL` in `meter.py`).
- **Agent-tool tax (per-model isolation impossible via subagents).** Every Agent dispatch — foreground OR background — writes the subagent's return into the parent's next-turn `cache_write_1h` at the parent's model rate (Opus, for interactive sessions). The displayed subagent cost is only the subagent's own tokens; the parent-side amplification is typically 10–30× more and shows up in the main-thread total. **For per-model A/B testing, use `claude -p --model X` subprocesses, not the Agent tool — run them sequentially, since parallel runs inflate cost via redundant cache writes.** Demonstrated empirically in research/per_model_cost_v5.md.
- **Background subagents are invisible to `agents` mode.** `run_in_background: true` Agent dispatches don't write `toolUseResult.totalTokens` to the parent JSONL. They still consume quota (the panel ticks) but `/usage2 agents` can't see them. Use foreground dispatch when you need per-spawn attribution.
- **Date-suffixed model names (e.g., `claude-haiku-4-5-20251001`) fall back to Sonnet pricing.** `claude -p` subprocesses sometimes write the full versioned model ID into their JSONL. The meter's `rates_for()` does a strict dict lookup and falls back to `DEFAULT_RATE_KEY` (Sonnet) for unknown keys, mis-attributing Haiku cost as Sonnet (3× higher). When using `claude -p` for measurement, trust the subprocess's stdout `total_cost_usd` directly — that's Anthropic's billing source of truth.
- **Hooks aren't separately attributed.** PostToolUse / PreCompact hooks that inject context show up in the next assistant turn's input count, not as their own line.
- **Quota panel scrape spawns a real `claude` process.** No LLM tokens, but ~12s of latency. The 10-min cache amortizes this.
- **Subscription tier display vs reality.** The "days of subscription fee" line is informational — it doesn't represent your actual cost (which is the flat monthly fee), it represents the API-equivalent value of what you consumed.
- **API rates can shift.** `RATES` is hardcoded in `meter.py` — update when Anthropic publishes new pricing.

## Failure modes

- `ERR: no JSONL found for project slug '...'` — fresh project with no transcript yet, or CC's slug-naming convention drifted.
- `ERR: could not capture /usage panel` — see `capture.sh` for tmux scrape failure modes.
- Calibration estimates wrong/wild — too few samples, or all samples are within the same quota window since reset. Take more samples across longer time spans.