The measurement compendium: every gauge, every layer

TL;DR. This is the master guide to measuring tokens and context with Claude Code: every instrument the platform gives you, organized into seven layers from "before the request exists" to "the whole team", with the exact command for each, what it can and cannot tell you, and how to make sense of the numbers once you have them. The spine is one table (question, instrument, precision); the flesh is a component price list for everything in your window, the five ratios that turn raw stats into diagnosis (with the normal ranges this book measured on real data), a billing-grade-versus-estimate honesty table, and recipes for building your own instruments on top of the transcript. Nothing here requires new theory: every number traces back to the usage block of Chapter 23; this chapter is about knowing which surface to read it from, and what to do next.

Contents

• The measurement stack
• Layer 0: before the request exists
• Layer 1: what is in the window right now
• Layer 2: what this turn cost
• Layer 3: what this session cost
• Layer 4: what this machine's history says
• Layer 5: what the team is doing
• Layer 6: benchmarking quality, latency, and change
• The component price list
• Making sense of it: the five ratios
• Which numbers to trust for what
• Building your own instruments
• Further reading
• Takeaways

The measurement chapters so far each took one instrument deep. This one is the map of all of them, because the practical failure is rarely "I cannot measure that"; it is reaching for the wrong layer: standing up a dashboard to answer a statusline question, or trusting a chars/4 estimate where a budget needed count_tokens. Match the layer to the question and every measurement in this book takes under a minute.

The measurement stack

Layers 0 to 2 are free and instant; 3 and 4 are a script over files you already have; 5 needs infrastructure; 6 needs a repeated task. The rest of the chapter walks them in order.

Layer 0: before the request exists

Exact counting is the API's count_tokens (Chapter 2, Chapter 23): free, no generation, and it counts the request the way it will be billed (system, tools, framing included). From a terminal, without writing code:

ant messages count-tokens --model claude-opus-4-8 \
  --message '{role: user, content: "@./CLAUDE.md"}' \
  --transform input_tokens -r

That one-liner is how you hold CLAUDE.md to its 500-token budget (Chapter 20), price a document before pasting it, or diff a prompt across two versions (count each, subtract). The estimates (chars/4, words * 1.3) remain fine for ratios and gut checks, wrong for budgets, and a foreign tokenizer like tiktoken is wrong for Claude, period.

Pre-flight also means pricing a change before you make it. Thinking of adding an MCP server, a skill, a hook? Layer 1 can measure it in two snapshots, next.

Layer 1: what is in the window right now

/context is the census of your live window, dissected field by field in Chapter 21: one row per category (system prompt, system tools, MCP tools, custom agents, memory files, skills, Messages, free space), each with a token count. Three uses beyond the glance:

• Component pricing by differential. /context, change one thing (add the MCP server, install the skill, register the hook), then /context again in a fresh session: the row delta is that component's standing price per session. This is the only reliable way to price things you do not control the rendering of, like another vendor's tool schemas.
• /mcp lists connected servers and their tools, the drill-down for a fat "MCP tools" row.
• The statusline (Chapter 25) carries the same data as machine-readable JSON on every turn: context_window.context_window_size, used_percentage, remaining_percentage, plus the full per-field current_usage. If you read /context more than twice a day, script the statusline instead and stop asking.

Layer 2: what this turn cost

The atom of all measurement is the usage block (Chapter 23): input_tokens + cache_creation_input_tokens + cache_read_input_tokens is the full prompt, output_tokens is the 5x half, cache_creation splits writes by TTL. Three surfaces expose it per turn:

• Statusline context_window.current_usage.*: live, after every assistant message.
• The transcript line for the turn (~/.claude/projects/<project>/<session>.jsonl): the block verbatim, plus model, timestamp, and the sidechain flag.
• Streaming, if you script against claude -p --output-format stream-json (--include-partial-messages for deltas): input-side fields arrive in message_start, authoritative output_tokens in the final message_delta, and wall-clock timing of the first content event gives you time-to-first-token, the latency number none of the token gauges show.

Layer 3: what this session cost

Five surfaces, each with a different emphasis:

The audit tool is the one to internalize, because it answers the three session questions at once: is caching healthy (the prefix column), where did the money go (per-turn cost), and what did caching save (the counterfactual line).

Layer 4: what this machine's history says

Everything above aggregates from the transcripts, so the transcripts can answer anything the gauges can, retroactively, for every session you have ever run (Chapter 25):

• usage_ledger.py: machine totals per model, the realized cache hit rate, actual versus uncached cost, most expensive sessions. This book's run: 7.0B prompt tokens, 96.8 percent hit rate, $32,266 saved by caching.
• npx ccusage daily|weekly|monthly: the same data as calendar reports; ccusage blocks --live is the burn-rate meter for the current 5-hour plan window, the gauge to keep open during an autopilot run; ccusage statusline feeds a compact version into your prompt.
• injection_census.py: the structural view: what the harness injected (22 types on this machine) and whether the prefix discipline held (98.1 percent of turn pairs, Chapter 28).

Layer 5: what the team is doing

One machine's transcripts stop at the machine. For a team, Claude Code's opt-in OpenTelemetry exporter (Chapter 25) emits claude_code.token.usage (dimensioned by type and model), claude_code.cost.usage, session counts, active time, and per-request events, sliced by user.email and organization.id. Point it at Langfuse, Grafana, Datadog, or Helicone (Chapter 26, Chapter 27) and the layer-4 questions become saved charts with alerts: cost per developer per week, cache hit rate trend, model mix. For API applications you build (not Claude Code itself), a gateway like LiteLLM adds enforcement to the measurement: budgets per key, on top of the reports.

Layer 6: benchmarking quality, latency, and change

Tokens are one axis. A complete benchmark of a context-engineering change reads four:

1. Cost and volume: the layer-3 instruments, before and after, under the Chapter 27 protocol (same task, /clear, one variable).
2. Turns: from the audit table or num_turns. Turn count is the compounding unit; a change that cuts per-turn tokens but adds turns can lose (Chapter 22).
3. Latency: duration_ms versus duration_api_ms from -p JSON separates model time from tool time; stream timing gives TTFT. Caching shows up here too: a warm prefix cuts time-to-first-token as well as cost.
4. Quality: the axis token gauges cannot see. promptfoo (Chapter 26) holds pass-rate constant while you cut tokens; the guided lab held "feature verified working" constant while cost halved. A benchmark without a quality gate is an invitation to ship cheap garbage.

The component price list

"Make sense of it" starts with knowing what each resident of your window costs. The method: read the rows off /context (or price by differential for anything you are considering adding), then classify each by how it costs. Real numbers from this book's own working session (Chapter 21):

The classification is the insight: prefix-priced components are nearly free once caching is healthy; conversation-priced components bill on every turn; on-demand components bill only when used. Optimization effort follows that order in reverse.

Making sense of it: the five ratios

Raw stats become diagnosis through ratios. These five, with the normal ranges this book measured on real data, are the interpretation layer:

1. Cache hit rate = cache_read / (input + write + read). Health, not efficiency. This machine runs 96.8 percent lifetime; a healthy working session sits 85 to 97. Below ~70 on a multi-turn session means resets or invalidators: audit for RESET rows (Chapter 24). And remember the paradox from the guided lab: the wasteful run had the higher hit rate. Never optimize this number upward; only investigate it downward.
2. Prompt:output ratio. This machine: 188:1 lifetime. High (>100:1) means agentic re-sending dominates, so bound history and cut reads; low (<10:1) means generation dominates, so shape output and check effort. This ratio tells you which half of the book to open.
3. Cost per turn, over the session. From the audit table. Flat is healthy (cache absorbing growth); climbing steadily means the window is bloating toward a /compact decision; a single spike is a reset or a giant read, both worth naming.
4. Tokens per completed task. The only number that survives arguments, because it holds outcome constant: the guided lab's 355k versus 139k for the same verified feature. Trend it across your recurring tasks; it is the KPI of everything in this book.
5. Output share of cost = 5 * out / (in + 1.25 * write + 0.1 * read + 5 * out) (per-token weights from Chapter 2 and 23). On cache-healthy sessions output is often a third to a half of spend despite being ~1 percent of tokens; when it dominates, terseness and effort outrank every input-side lever.

Then diagnose by symptom, the landscape decision guide with its metrics attached: "expensive" starts at ratio 2 (which half?), "slow" at layer 6's latency split (model or tools?), "forgets" at /context free space and the compaction history, "cache broken" at ratio 1 and the audit's prefix column.

Which numbers to trust for what

Not all surfaces are billing-grade, and mixing grades is how dashboards lie:

The rule: compare like with like (audited dollars against audited dollars, plan bars against plan bars), and when a decision touches real money, recompute from token fields and current prices rather than trusting any tool's cached table, including this book's.

Building your own instruments

The five scripts shipped with this part are a toolkit, not a product, and the transcript format rewards small extensions (parse defensively; the format is internal, Chapter 25):

Remember. The layers exist so you never over-instrument. A statusline question answered with a dashboard costs a week; a budget question answered with chars/4 costs real money. Start at layer 0 and walk down only while the question remains unanswered; in this book's experience, almost everything resolves by layer 4, on data your machine already wrote.

Further reading

• The deep chapters behind each layer: 21 (gauges), 23 (the usage block), 24 (cache rules), 25 (transcripts and OTel), 27 (the A/B protocol), 29 (the worked experiment).
• Claude Code docs (code.claude.com/docs): "Manage costs effectively", "Monitoring usage", "Statusline", and the CLI reference for -p output formats.
• shared token-counting and pricing pages on platform.claude.com/docs, the source of truth the estimate-grade tools approximate.

Takeaways

• Measurement is a seven-layer stack: pre-flight counting, the live window, the turn, the session, the machine's history, the fleet, and comparative benchmarks. Match the layer to the question; layers 0 to 4 are free and already on your disk.
• Price the window as components: prefix-priced (system, tools: nearly free when cached), conversation-priced (CLAUDE.md, hook output, Messages: paid every turn), on-demand (skills). Differential /context snapshots price anything you are considering adding.
• Interpret through the five ratios: cache hit rate (health, 85 to 97 normal, never optimize upward), prompt:output (which half of the book to open), cost per turn (flat is healthy), tokens per completed task (the real KPI), output share of cost (when terseness outranks everything).
• Know your grades: usage-block fields are billing-grade; every dollar figure outside your invoice is a computed estimate; plan bars are not dollars; estimates are for ratios.
• Benchmark on four axes (cost, turns, latency, quality) with a quality gate, or the measurement will happily optimize you into garbage.
• Extend the toolkit rather than adopting a platform, until the question is genuinely about a team: a dict key change turns the ledger into a per-branch, per-day, or per-subagent report.

👉 That is the complete measurement story: every gauge, every layer, and the ratios that turn readings into decisions. What remains is practice: the professional workflow that makes all of it routine. Continue to A professional workflow.