Menu
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-projection |
| description | 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). |
| argument-hint | [--window 7d] [--horizons 7d,30d,90d,365d] [--format table|json] |
| allowed-tools | Bash |
Forward-looking cost projection that pairs with cost-budget-check:
cost-budget-check answers "have we crossed the line?" — reactivecost-projection answers "when will we cross the line?" — predictivesession-* records from the cost-tracking namespace (same source cost-budget-check uses).capturedAt/startedAt).windowSpend / windowDays.budget-config key set by cost-budget set):
ALREADY REACHED markers for thresholds already exceeded.--window Measurement window. Nh|Nd|Nw|Nm. Default 7d.
--horizons Projection horizons. Default 7d,30d,90d,365d.
--format table|json Default table (markdown).
Env: PROJECTION_NAMESPACE override (default cost-tracking), PROJECTION_QUIET=1 (alias for --format json).
| Sessions in window | 3 |
| Window spend | $3.000000 |
| **USD per day** | **$0.428571** |
| All-time spend | $3.000000 across 3 sessions |
## Projected spend (linear extrapolation)
| Horizon | Days | Projected spend |
|---|---:|---:|
| 7d | 7 | $3.0000 |
| 30d | 30 | $12.8571 |
## Budget exhaustion ($20.00 configured)
| Threshold | Target | Remaining | Time at current rate |
|---|---:|---:|---|
| 75% | $15.00 | $12.00 | 28.0 days |
| 90% | $18.00 | $15.00 | 35.0 days |
| 100% | $20.00 | $17.00 | 39.7 days |
cost-projection --format json | jq '.budget.exhaustion[2].daysUntilReached < 7' → fail builds when 100% exhaustion is < 1 week away.Linear extrapolation assumes the current rate holds. The footer reminds operators to re-run after workload shifts. For drift detection over MULTIPLE windows, pair with cost-trend (which already covers benchmark-drift).
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.
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.