# Budget Set

Define a spend budget for Claude Code and, optionally, create a cost alert rule that...

- Repository: https://github.com/hoangsonww/Claude-Code-Agent-Monitor (1136 stars)
- Category: AI and agents
- License: MIT
- Last updated: 2026-10-31
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add hoangsonww/Claude-Code-Agent-Monitor --skill budget-set -g -a claude-code -y`
Codex: `npx skills add hoangsonww/Claude-Code-Agent-Monitor --skill budget-set -g -a codex -y`
Cursor: `npx skills add hoangsonww/Claude-Code-Agent-Monitor --skill budget-set -g -a cursor -y`
Gemini CLI: `npx skills add hoangsonww/Claude-Code-Agent-Monitor --skill budget-set -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add hoangsonww/Claude-Code-Agent-Monitor`

## Description

Define a spend budget for Claude Code and, optionally, create a cost alert rule that fires when usage crosses the limit, via POST /api/alerts/rules on the Agent Monitor dashboard. Reads current spend from /api/pricing/cost to size the budget sensibly and explains every rule field before writing. Use when setting a spend limit or wiring up a budget guardrail.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Budget Set

Help the user define a spend budget and turn it into a live cost guardrail on the
Agent Monitor dashboard.

## Input

The user provides: **$ARGUMENTS**

This is the budget to set, e.g. `"$50/month"`, `"$10/week"`, or `"200000 tokens"`.
If a period is omitted, treat it as a monthly budget and say so. If no number is
given, read current spend first and propose a target.

## Data Sources

| Endpoint | Returns |
|----------|---------|
| `GET /api/pricing/cost` | `{ total_cost, breakdown: [{ model, input_tokens, output_tokens, cache_read_tokens, cache_write_tokens, cost, matched_rule }] }`, current spend, used to size the budget and compute the blended $/token rate |
| `GET /api/alerts/rules` | `{ rules: [{ id, name, rule_type, config, enabled, cooldown_seconds }] }`, existing rules, so you don't create a duplicate guardrail |
| `POST /api/alerts/rules` | Create a rule. Body: `{ name, rule_type, config, enabled?, cooldown_seconds? }`. Returns `{ rule }` |

## How a budget becomes a rule

The dashboard's alerting engine fires on **tokens**, not dollars. The spend-relevant
rule type is **`token_threshold`**, whose config is `{ total_tokens }`, it fires when
a session's cumulative tokens (input + output + cache_read + cache_write) cross the
threshold. To turn a **dollar** budget into a token ceiling:

```
blended_rate_per_token = total_cost / total_tokens          # from /api/pricing/cost
token_ceiling          = budget_dollars / blended_rate_per_token
```

Compute `total_tokens` by summing the four token columns across the cost `breakdown`.

### Rule fields explained

The rest: https://github.com/hoangsonww/Claude-Code-Agent-Monitor/blob/HEAD/plugins/ccam-cost-guard/skills/budget-set/SKILL.md