budget-guard

budget-guard stops a Claude Code session before it spends past a limit you set. It guards three figures: the session cost in dollars, and how much of your plan’s 5-hour and 7-day windows is used. While all three sit under their limits it shows nothing at all. The same author’s context-lens, quota-meter and token-ledger keep figures like these on screen the whole time; budget-guard only speaks up near a limit, and past it, it refuses to keep working. It is for anyone on a plan with a quota, or paying per token, who wants a hard stop rather than a readout.

What it does

• At 80% of a limit, the default warn mark, it toasts once and pins a line under the prompt such as cost $4.10/$5.00 82% · 5h 71/90% · 7d 15/95%. The line stays while any figure is at warn or over and clears when all of them drop back under. The toast is not repeated until a level changes.
• Past a limit in block mode, the default, the next tool call is refused, a subagent’s included, and the turn is stopped, because a model refused one tool tries another and every try is a billed API call. Sending the next prompt opens a question, Send anyway or Do not send: the first grants an override for that one turn, the second drops the prompt and prints why.
• In warn mode nothing is refused. You get one toast per turn and the pinned line.
• /guard on its own prints each figure against its limit and where the settings are kept. /guard cost 5, /guard 5h 90 and /guard 7d 95 set the limits, with 0 turning a guard off. /guard warn and /guard block switch the mode, /guard override lets the next turn run regardless, and /guard off and /guard on switch the whole guard. An override lasts exactly one main turn; a subagent’s turn ending inside it does not use it up.

Install

Needs Claude Code 2.1.287 or later in an interactive terminal. The 5-hour and 7-day guards need a Claude subscription; the cost guard works on an API key too.

claude plugin marketplace add Arunjay4213/claude-mods
claude plugin install budget-guard@claude-mods

The marketplace is the author’s own claude-mods, unrelated to this site. Restart Claude Code. The cost guard ships off, with costLimitUsd at 0, so the first step is to set one: /guard cost 5 caps this session at five dollars. The window limits start at 90% and 95%.

How it works

Every reading comes from $.session.usage() called with no argument, the form that reports what the last API response already carried and computes nothing. cost.usd is the same dollar figure /cost shows, so there is no price table of its own. The window percentages come from the response’s rateLimits, kinds five_hour and seven_day, rounded to a whole percent. The mod reads at session.start, after every turn, and again inside tool.call and prompt.submit before it decides, because cost moves while a turn runs. The first tool.call read is timed once per session: under 30 ms, every check reads live; slower than that, readings are cached for 3 seconds.

To block, the tool.call hook returns a deny with the reason and, a quarter of a second later, aborts the running main turn through $.turn.abort, so the refusal lands in the transcript before the stop does. The AskUserQuestion tool is exempt, because the guard’s own question goes through it. At prompt.submit it opens $.ui.ask; slash commands always pass, so /guard override can still be typed. A dismissed dialog counts as Do not send.

The six settings are the plugin’s userConfig fields, so /config shows them too:

Field	Default	What it is
costLimitUsd	0	Dollars this session may spend. 0 turns the cost guard off.
fiveHourLimitPercent	90	Percent of the 5-hour plan window allowed. 0 turns it off.
sevenDayLimitPercent	95	Percent of the 7-day plan window allowed. 0 turns it off.
warnAtPercent	80	How far along a limit counts as a warning.
mode	block	block refuses work past a limit, warn only says so.
enabled	true	Turns the whole guard off without uninstalling it.

/guard writes a change through $.config.set, which lands in ~/.claude/settings.json under pluginConfigs["budget-guard"].options, so it survives a restart. Claude Code reloads the module when its options change, which is why /guard cost 5 is followed by a short “options changed” notice. If a host refuses the write, the same fields go to $.store under settings and /guard says “Kept in the plugin store”. The override and the last announced levels live in memory only.

The module makes no network calls of its own and reads no files; everything arrives through the engine. The only text that reaches the model is the one-line deny reason.

Limitations

• A hook that throws or times out is skipped by the engine, and anyone can type /guard off. The author calls it a guard rail, not a lock.
• The deny refuses the next tool call. API calls already running finish and are billed, so the cost can land about one model step past the limit.
• Cost settles as each API response is accounted for, so a short single-step turn can end past the limit with nothing refused. The next prompt is then caught at prompt.submit.
• API-key sessions report no plan windows, so the 5-hour and 7-day guards stay inactive. /guard says so.
• In claude -p or an SDK run there is no one to ask, so a prompt over a limit is dropped with the reason. /guard override or a higher limit is the way through.
• Terminal sessions only. The author wrote it against Claude Code 2.1.272.