forecast — Claude Code command: month-end spend projection
forecast projects what you will spend by the end of a week or month: it pulls session counts and cost from the dashboard on localhost:4820 and extrapolates from the average per session.
MIT ★ 1,198 updated 2026-10-23
/plugin marketplace add hoangsonww/Claude-Code-Agent-Monitor
/plugin install ccam-cost-guard@claude-code-agent-monitor-pluginsWhat forecast does
The command takes week or month; with no argument it works on the month. It fires two requests at the local dashboard, http://localhost:4820/api/analytics and http://localhost:4820/api/pricing/cost, and reads per-day session counts, the session total and total_cost.
Then the arithmetic: average cost per session, average daily spend across the last 7 days, days left in the chosen period, and the projected total. You get spend-to-date, avg_daily_spend, days_remaining and the end-of-period figure in USD to 4 decimals. A ▲ or ▼ marks whether the 7-day pace sits above or below the trailing 14-day one.
Daily spend is estimated from session counts, so read the number as a trend. The dashboard must be running on localhost:4820. If it is not, the command asks you to start it with npm start from the repo root. Nothing gets modified.
What it helps with
- project month-end API spend from the current trend
- catch a week that is burning faster than the previous two
- estimate what is left to spend before the period closes
- read the figure off the dashboard without opening a browser
Example prompts for the agent
/forecast month— project spend to the last day of the month/forecast week— how much will we burn by Sunday?- Run forecast against the dashboard and show
avg_daily_spend
How to install forecast
1Plugin marketplace
/plugin marketplace add hoangsonww/Claude-Code-Agent-Monitor/plugin install ccam-cost-guard@claude-code-agent-monitor-plugins2Manually: put the files in place
.claude/commands/forecast.mdCall it with /forecast. For all projects use ~/.claude/commands/
Manually: put the files in place
~/.codex/prompts/forecast.mdCall it with /prompts:forecast. Codex marks this format deprecated in favour of skills
Manually: put the files in place
.github/prompts/forecast.prompt.mdManually: put the files in place
.gemini/commands/forecast.tomlGemini stores commands as TOML: the prompt text goes into the prompt field
Questions about forecast
How do I install forecast in Claude Code?
Add the marketplace with /plugin marketplace add hoangsonww/Claude-Code-Agent-Monitor, then install the plugin: /plugin install ccam-cost-guard@claude-code-agent-monitor-plugins. The command itself lives in .claude/commands/forecast.md.
What does forecast do?
It works out average daily spend and carries it forward to the end of a week or month using dashboard numbers. Output is spend-to-date, avg_daily_spend, days_remaining and the projection in USD to 4 decimals.
What does forecast need to run?
A dashboard listening on localhost:4820 with /api/analytics and /api/pricing/cost responding. When it is down, the command tells you to bring it up with npm start from the repo root.
Source text
forecast.md · MIT
---
description: Quick month-end spend projection from the daily trend
argument-hint: "[week|month]"
---
Give a quick spend projection for the end of the **$ARGUMENTS** period (`week` or
`month`; default `month` if empty).
1. Fetch the trend and current spend in parallel:
```
curl -s http://localhost:4820/api/analytics
curl -s http://localhost:4820/api/pricing/cost
```
From `/api/analytics` read `daily_sessions` (`[{ date, count }]`) and the session
total; from `/api/pricing/cost` read `total_cost`.
2. Project:
- `avg_cost_per_session = total_cost / total_session_count`.
- `avg_daily_spend = mean(last 7 days of daily_sessions[].count) × avg_cost_per_session`.
- `days_remaining` = days left until end of the chosen period (week → Sunday; month → last calendar day).
- `projected_total = total_cost + avg_daily_spend × days_remaining`.
3. Print: spend-to-date, `avg_daily_spend`, `days_remaining`, and the **projected end-of-period total** (USD, 4 decimals), with a ▲/▼ note on whether the 7-day pace is above or below the trailing 14-day pace.
State that daily spend is approximated from session counts. If the dashboard is
unreachable, tell the user to start it with `npm start` from the repo root. Keep it to
a few lines. Read-only — do not modify anything.
© Son Nguyen · MIT · hoangsonww/Claude-Code-Agent-Monitor