Menu
Per-message cost breakdown within a single session. The drill-down companion to cost-anomaly — when an outlier session is flagged, this surfaces the specific expensive messages so operators can see whether the cost came from output tokens, cache writes, or model escalations.
MAD-based outlier detection on session spend. Robust to the very outliers it hunts (unlike mean+sigma). Surfaces specific anomalous sessions with modified-z scores; optional --alert-on-outliers exit code for CI gates. Distinct from cost-burn (aggregate trend) — this answers "which INDIVIDUAL session is the outlier?".
Burn-rate trend over time with optional drift-alert exit code. Bins session spend into buckets, surfaces window-over-window delta, and can exit 1 when latest bucket exceeds prior mean by a configurable %. Distinct from `cost-trend` (benchmark drift); this tracks PRODUCTION spend trajectory.
Multi-baseline counterfactual cost analysis. Compares actual session spend to hypothetical always-haiku / always-sonnet / always-opus routing baselines. Answers "is the routing earning its keep?" Negative savings flag over-escalation; positive savings quantify the router's win.
Snapshot delta between two cost-summary JSON outputs. PR-level cost regression detection — answers "what changed between these two specific snapshots?". Pairs with cost-summary's stable JSON contract.
Composite CI gate — runs cost-budget-check + cost-burn + cost-anomaly + cost-projection in parallel and surfaces a single combined health status with max exit code. The operationally-useful entry point — one shell-out covers all four alert ladders.
Forward-looking spend extrapolation. Computes a USD-per-day rate from the recent measurement window, projects to 7d/30d/90d/365d horizons, and surfaces "days until budget exhausted" when a budget is configured. Predictive counterpart to `cost-budget-check` (reactive).
| name | cost-session |
| description | Per-message cost breakdown within a single session. The drill-down companion to cost-anomaly — when an outlier session is flagged, this surfaces the specific expensive messages so operators can see whether the cost came from output tokens, cache writes, or model escalations. |
| argument-hint | [--session-id <id>] [--top 20] [--since <iso-ts>] [--format table|json] |
| allowed-tools | Bash |
When cost-anomaly flags a session as a >3.5σ outlier, the next question is "which MESSAGES were expensive?". cost-session answers that.
| Question | Skill |
|---|---|
| "Which sessions cost the most?" | cost-conversation |
| "Which sessions are outliers?" | cost-anomaly |
| "Which messages in THIS session were expensive?" | cost-session ← this |
Implementation: scripts/session.mjs.
--session-id <id> (scans ~/.claude/projects/*/)
or --latest (default; picks most-recently-modified jsonl).usage blocks._prices.mjs).cost_usd, surface top-N (default 20).Example real session, top message:
| # | Model | In | Out | Cache W | Cache R | Cost |
| 1 | opus-4-7 | 6 | 569 | 881898 | 0 | $16.58 |
Without the Cache W column it looks like "569 output tokens cost $16" — that's wrong by 380×. The actual cost is ephemeral 1h cache write at opus pricing: 881,898 tokens × $18.75/1M = $16.54.
Operators reading the table see immediately: "the model wrote 881K tokens to ephemeral cache". From there the question becomes "why did we cache 881K tokens of context for a 6-input request?" — that's a real engineering signal.
# Step 1: find outliers across all sessions
cost anomaly --alert-on-outliers 1 || cost anomaly # see which session-ids
# Step 2: drill into the flagged session
cost session --session-id <flagged-id> --top 10
# Step 3: open that jsonl at the timestamp the top message reports,
# inspect the prompt + tool calls
Top of output:
| p50 (median) message | $0.85 |
| p90 message | $1.45 |
| p99 message | $1.74 |
Lets operators ask "is this top message a 2× outlier or a 380× one?" without having to compute it themselves. The "top is >2× p99" footer fires when the answer is "yes, this is an in-session outlier worth investigating".
Useful for drilling into a specific time range within a long session:
cost session --since 2026-06-16T13:00:00Z --top 5
Only messages with timestamp >= --since are considered.
--session-id not found in any project's jsonls → exit 2 with error.--top must be a positive integer → exit 2.