Skip to main content
command CX Codex

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

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add hoangsonww/Claude-Code-Agent-Monitor
/plugin install ccam-cost-guard@claude-code-agent-monitor-plugins
Open on GitHub

What 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-plugins

2Manually: put the files in place

.claude/commands/budget.md

Call it with /budget. For all projects use ~/.claude/commands/

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

Similar slash commands

All slash commands for Agent setup: memory, context, orchestration →

From the same set155

The whole set →
top-spenders top-spenders sorts Claude Code sessions by cost and lists the most expensive ones. Use it to inspect session spending and compare the top entries with the total. CX Codex +1 ★ 1,198repo stars runs Pulls recent Workflow-tool fleet runs from the local Agent Monitor and prints a status summary plus a compact table of the latest ones. CX Codex +1 ★ 1,198repo stars recent recent fetches the latest Claude Code sessions from Agent Monitor with costs and run statuses. Useful when you need a quick summary of agent activity and spending. CX Codex +1 ★ 1,198repo stars ship-feature ship-feature — a workflow for taking medium or large feature changes from module inspection through implementation, verification, and documentation updates. Covers backend, frontend, and MCP work. CX Codex +1 ★ 1,198repo stars tail-events tail-events fetches recent events from a local Agent Monitor dashboard and displays them in a compact table. Useful for tracking agent tool calls and session state. CX Codex +1 ★ 1,198repo stars mcp-operations The mcp-operations skill guides local MCP server checks, host configuration, and safety settings. Use it when tool connectivity fails or MCP behavior changes. CX Codex +1 ★ 1,198repo stars errors errors pulls recent APIError events from the local Agent Monitor dashboard and prints one line per failure: time, session, short summary. CX Codex +1 ★ 1,198repo stars cost-today cost-today fetches total token spending and single-line per-model expenses from Agent Monitor. CX Codex +1 ★ 1,198repo stars

Project sponsors

Companies that keep this analytics open