spend-forecast

1# Spend Forecast
2 
3Project where Claude Code spend will end up by the close of the current week or month.
4 
5## Input
6 
7The user provides: **$ARGUMENTS**
8 
9This is the forecast horizon — `"week"`, `"month"`, or a specific date. Default to
10**month** (calendar month-end) when nothing is given, and state the horizon you used.
11 
12## Data Sources
13 
14| Endpoint | Returns |
15|----------|---------|
16| `GET /api/analytics` | `{ total_cost, tokens (effective totals, baselines pre-summed), daily_sessions (365d: [{ date, count }]), daily_events, overview, ... }` — `daily_sessions` is the trend the forecast extrapolates |
17| `GET /api/pricing/cost` | `{ total_cost, breakdown: [{ model, input_tokens, output_tokens, cache_read_tokens, cache_write_tokens, cost, matched_rule }] }` — authoritative spend-to-date and avg cost-per-session input |
18| `GET /api/sessions?limit=200` | Session list with inline `cost` and `started_at` — group by day for a sharper daily-spend curve than the count-based approximation |
19 
20## Forecast method
21 
22Spend has no native per-day field, so build a daily-spend series and extrapolate:
23 
241. **Spend-to-date** = `total_cost` from `/api/pricing/cost`.
252. **Avg cost per session** = `total_cost / total_session_count`.
263. **Daily spend series**: for the trailing window, `daily_spend[d] ≈ daily_sessions[d].count × avg_cost_per_session`. For a sharper curve, instead sum inline session `cost` grouped by `DATE(started_at)`.
27…