budget — Claude Code command: what it does, how to install
Puts your Claude spend next to a monthly budget you name, then tells you whether you are under it, on pace or already over.
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 budget does
Pass a monthly dollar figure and the command calls curl -s http://localhost:4820/api/pricing/cost for the running total and a per-model breakdown. The report stays short: money spent so far in USD to four decimals, the budget you gave, and the share of it already used.
A ▲ or ▼ beside that percentage shows where you sit against a straight-line pace for today's date in the month. Then a verdict (under budget, on pace, over budget) and the three costliest models with their slice of the total. Run it with no argument and it reports the total alone, then asks for a budget. It only reads.
The dashboard has to be running first. When the call to localhost:4820 fails there is no cost data to compare, so start it with npm start from the repo root and call the command again.
What it helps with
- see what has been spent on Claude so far
- compare the running total against a monthly budget
- check whether spending runs ahead of a straight-line pace
- find which models take the biggest share of the bill
- spot an overrun while there is still month left
Example prompts for the agent
- /budget 50
- /budget 200
- /budget
How to install budget
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/budget.mdCall it with /budget. For all projects use ~/.claude/commands/
Manually: put the files in place
~/.codex/prompts/budget.mdCall it with /prompts:budget. Codex marks this format deprecated in favour of skills
Manually: put the files in place
.github/prompts/budget.prompt.mdManually: put the files in place
.gemini/commands/budget.tomlGemini stores commands as TOML: the prompt text goes into the prompt field
Questions about budget
How do I install budget in Claude Code?
Add the marketplace first: /plugin marketplace add hoangsonww/Claude-Code-Agent-Monitor. Then run /plugin install ccam-cost-guard@claude-code-agent-monitor-plugins. The command itself sits in .claude/commands/budget.md.
What does the budget command do?
It pulls total spend and a per-model breakdown from the local dashboard, prints the amount used, the percentage of your budget and a verdict on pace.
Why does budget return no numbers?
The dashboard on localhost:4820 is not up. Start it with npm start from the repo root, then run the command again.
Source text
budget.md · MIT
--- description: Show current Claude Code spend versus a budget number argument-hint: "[monthly-$]" --- Show current Claude Code spend against the budget **$ARGUMENTS** (a monthly dollar figure, e.g. `50`). If `$ARGUMENTS` is empty, just report spend-to-date and ask for a budget. 1. Fetch current spend: ``` curl -s http://localhost:4820/api/pricing/cost ``` Read `total_cost` (spend-to-date) and the per-model `breakdown`. 2. Print a concise budget status: - **Spend to date**: `total_cost` as USD to 4 decimals. - **Budget**: `$ARGUMENTS`/month. - **Consumed**: `total_cost / budget × 100`% — with a ▲/▼ vs. the linear pace expected for today's day-of-month (`budget × day_of_month / days_in_month`). - **Verdict**: under budget / on pace / over budget. - **Top 3 models by cost** from the breakdown (model, cost, % of total). If the dashboard is unreachable (curl fails / empty), tell the user to start it with `npm start` from the repo root. Keep the output to a few lines plus one small table. Currency as USD to 4 decimal places. Read-only — do not modify anything.
© Son Nguyen · MIT · hoangsonww/Claude-Code-Agent-Monitor