Claude Code Cost Analysis

A framework and ready-to-use query shapes for analyzing Claude Code usage costs across a team or org.

Prerequisites: you need Claude Code telemetry

Claude Code can export usage as OpenTelemetry metrics and events (CLAUDE_CODE_ENABLE_TELEMETRY=1 plus an OTLP endpoint — see the Claude Code monitoring docs). Point that export at an observability backend (Honeycomb, Datadog, an OTLP collector into a warehouse, etc.). This skill analyzes that data.

The example queries in references/queries.md are written for Honeycomb (environment/dataset names are placeholders — substitute wherever you send telemetry). The analysis dimensions and cost formulas are backend-agnostic — the same shapes translate to any store that has per-api_request rows with token counts, cost_usd, model, and session.id.

A few attribute names in the examples (user.email, speed, skill.name, normalized_file_path) are enrichments that depend on your telemetry pipeline and Claude Code version — verify column names against your own data (get_dataset_columns or the equivalent) before relying on them. Numeric fields are sometimes stored as strings; cast with FLOAT(...) before aggregating (see the query examples).

Analysis Dimensions

Each dimension answers a different question. Run whichever are relevant — there is no required order, though broader dimensions provide context for narrower ones.

Apply cost formulas from references/cost-model.md when computing dollar estimates from token counts.

Illustrative Findings

These are shape-of-the-problem findings from one large deployment — useful to calibrate expectations, not ground truth for your org. Always verify against fresh queries against your own data.

Cost distribution

Session turn phases

Tool result sizes (typical ranges)

Context window behavior

• A small fraction of sessions trigger auto compaction.
• The most expensive sessions rarely compact — they grow to a large context and stay just below the window limit.
• Sessions on smaller context windows compact more often and cost far less per call than sessions on the largest window with equivalent workloads.

Key Analysis Patterns

Matched session comparison

The most compelling way to demonstrate context-size impact on cost is finding two sessions with similar API-call counts but different context behaviors — one with high average cache_read (bloated, likely on the largest window) and one low (lean, compacting or on a smaller window). The per-session query (Section 6a adapted to break down by session.id) surfaces these pairs.

User segmentation by context usage

Classify users by what % of their calls exceed a large cache_read threshold (Section 6a, calls_over_200k field):

• 0% over threshold — never needs the largest context, would work on a smaller window
• 1-10% — rarely needs it, benefits most from proactive compaction
• 60%+ — genuinely needs the largest context (investigate what tools drive it via Section 6b)

Important Caveats

Quality vs cost tradeoff: Cost optimizations (model downshift, aggressive compaction, smaller context windows) may degrade output quality. Measure quality objectively before changing configuration. Cost savings mean nothing if the tool becomes less useful.

Caching IS helping: Prompt caching reduces the bill substantially vs uncached input. The remaining cost is driven by the volume of cached tokens, not by caching being inefficient.

Instructions are a small share: CLAUDE.md files, rules, and skills are a small fraction of total spend. The real cost drivers are session length and context accumulation from tool results.

Turn-counts overcount command-level waste: a wasteful command (polling, re-auth, a bare sleep, a no-op) bundled into a turn that also does real work bills cache-read for that turn regardless — the marginal waste is close to zero. Classifying "turns containing pattern X" as waste massively overcounts. Separate standalone waste from bundled work by inspecting the actual command strings, and always back a dollar figure with atoms → examples → a reproducible query → an independent cross-check. See references/command-attribution.md.

Automated eval/test traffic pollutes usage totals: if you (or your telemetry pipeline) run automated eval or regression suites through Claude Code, that traffic is not real engineer usage. Tag or otherwise identify it in your export and exclude it from normal cost/context/compaction analysis; run a separate, intentionally-scoped query when you want to measure what the eval suite itself costs.

Generating Reports

Capture findings in markdown reports. See references/report-templates.md for standard structures. Name files {report-type}-{YYYY-MM-DD}.md.

Reference Files

• references/queries.md — Example Honeycomb queries organized by analysis dimension. Load when composing a query for a specific analysis dimension.
• references/cost-model.md — Token pricing ratios, per-call/per-session cost formulas, caching economics. Load when a finding needs a dollar estimate, not just a raw count.
• references/report-templates.md — Standard report structures for each analysis type. Load before writing up findings.
• references/column-gotchas.md — Data-quality gotchas specific to cost analysis. Load before trusting a cost or sequence column you haven't queried before.
• references/command-attribution.md — Attributing cost to specific command patterns (waste vs bundled with real work). Load when classifying whether a costly command is standalone waste or bundled with real work.

Scripts

• scripts/compute_percentiles.py — Compute p10/p25/p50/p75/p90/p99 from per-user query result sets