/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:

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

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

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

Modes:

\* 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?":

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.