mock

onbudget

Give a Claude Code task a spending limit, in dollars or as a share of your 5-hour or weekly usage; Claude sees what's left as it works, and onbudget stops it before the limit runs out.

/onbudget $3 Implement authentication
/onbudget 10% 5h Build this application
/onbudget week Write the migration

Install (Claude Code 2.1.287 or later):

claude plugin marketplace add sebastiandrazsky/onbudget
claude plugin install onbudget@onbudget

What you see, rendered by Claude Code with a scripted model: Claude Code 2.1.306 in an 80-column terminal, with the test suite's scripted model answering in place of Claude, at no cost. The three passages are copied from the screen as drawn, and nothing in them is edited.

  ⚠ onbudget: tier MEDIUM · $0.21 left · budget $0.50

⏺ [onbudget] Stopped: $0.07 of $0.12 is used, and the next request could cost up
  to $0.07, so it was not sent.
  This notice comes from the onbudget plugin, not from Claude. The work was
  interrupted: treat anything Claude has not reported as complete and verified
  as unfinished.
  To go on: /onbudget off (no budget), or /onbudget <budget> <instructions> (a
  new budget).

⏺ onbudget: Claude ended the task with STATUS: COMPLETE, at $0.20 of
  $0.50. The budget is still open: a follow-up prompt draws on it, and
  /onbudget off removes it.

The first line is Claude Code's status line under the prompt: the tier, what is left before the stop, and the budget. The second passage is a stop, under a $0.12 budget. The third ends a task.

• Reads the session's cost ledger and usage-window readings, its id and model, three environment variables (none a secret), and its own store.
• Writes its own store (~/.claude/plugins/store/onbudget_*.json), a status line, and, only with ONBUDGET_LOG=1, an event log in its own folder. Nothing else.
• Sends nothing anywhere. No network calls, no commands, no credentials. With no budget set it changes no request.

When you don't need it: in claude -p, Claude Code's own --max-budget-usd did as well as onbudget in our runs (Claude Code 2.1.304, n = 2 against 3). And at the 5-hour limit, Claude Code may let a response in progress finish under its Wrap-Up Allowance.

What it guarantees, and in which units

• The stop comes before the request. onbudget sits on Claude Code's model-request hook. When the spend so far, plus what the dearest request of the task has cost, would reach the budget, the next request is answered by the plugin with a notice and never reaches the API. Requests already running are not cancelled, and each one holds back its own reserve.
• Two documented ways past it. One request that costs more than any before it, because nothing can price a request before it is sent; and Claude Code's own requests that do not pass through that hook, the next-prompt suggestion between turns and a compaction. Both are counted, and both are under Limitations.
• Dollars are list-price dollars as /cost counts them, read from Claude Code's own ledger, subagents included. onbudget does no pricing of its own.
• Window budgets are in whole points of the window, for the whole account, as Claude Code reports them. 10% 5h is ten points of the 5-hour window, not ten percent of what is left. 5h is what the 5-hour window has left below 99% when you set the budget. A weekly budget (week, N% week) is counted in the weekly window's own points unless you set usdPerPointWeek, and is good to about a point.
• Every budget is also bounded by what the account has left. While a budget is open, both windows count as limits, and onbudget stops short of either one with its own notice (at 99%, or about 97% when it counts the window's points), before Claude Code's limit message would end the session in the middle of a request.
• It lands early. The model reads where the stop is and wraps up before it. In the second round the three onbudget runs ended by themselves at tier LOW with 19 to 25% of the budget unspent.
• Idle means idle. With no budget set, onbudget adds nothing to Claude's context and changes no request.

Results

The benchmark: seven real bug fixes in Python libraries (boltons, falcon, markdown-it-py, pluggy, pydantic-settings and two in werkzeug), given in one prompt to one headless session and scored by upstream tests the model never saw. eval/TASKS.md names each task's repository, commits and hidden tests. Claude Opus 5.5 at medium effort; REPORT.md has the method, both rounds' full tables and the exceptions, and eval/ the raw data. That evidence, the harness included, is at the tag v0.1.0: from 0.1.1 it is not on main, so an install does not carry it.

At $2.47 on Claude Code 2.1.304 (the release current on 2026-10-20):

	n	Tasks complete, of 7	Within $2.47	Ended by itself, with a report	Cost, each run
onbudget	3	5, 5, 5	3 of 3	3 of 3	$2.00, $1.86, $1.97
Plain, --max-budget-usd 2.47	2	5, 6	2 of 2	2 of 2	$2.06, $2.25
Budget sentence in the prompt	2	5, 5	2 of 2, one only because a safety cap refused its next request	1 of 2	$2.38, $2.10

• No onbudget run has gone over its budget: 12 runs with the real model, on Claude Code 2.1.289 and 2.1.304 (10 seven-task sessions and 2 single tasks). 11 of the 12 ended by themselves with a report.
• On 2.1.304 it is parity: onbudget finished no more tasks than plain Claude Code under its own cap or a sentence in the prompt. With n of 2 or 3, a difference of a task or less is noise. The six-task --max-budget-usd run did most of its work in seven subagents that Claude Code ran on Claude Sonnet 5.5 ($1.32 of its $2.25); the other, Opus only, finished 5 of 7.
• The build that ships is not byte for byte the one round two ran (git tag eval-freeze-3). git diff eval-freeze-3 -- hooks .claude-plugin shows these changes: weekly sizing (a weekly budget counts the window's points unless usdPerPointWeek is set); display text (the command's answers, the status line, the end-of-task line and the manifest's descriptions); the event log, which is off unless ONBUDGET_LOG=1 and goes only to log/events.jsonl in the plugin's own folder, where round two's build wrote it to a file the variable named; the variable ONBUDGET_EFFORT, removed, so that the effort option alone sets the cap (default medium, as before); an icon; from 0.1.1, the version number and the manifest's listing fields; and, from 0.1.2, other sessions' expired records gone through once a day instead of at every session start. Rendered side by side with tests/e2e/modeltext.py, what the model receives is byte for byte the same under dollar and 5-hour budgets, which is what round two ran, and differs only under weekly budgets.
• On 2.1.289, with an earlier build of onbudget (git tag eval-freeze), plain Claude Code under a cap split the work across subagents in six of eight runs and was cut off mid-work; that round's table is in REPORT.md.
• Every run had a one-line ~/CLAUDE.md in context, a pointer to a writing-style skill.

How it relates to what Claude Code already does

• --max-budget-usd works in print mode and the SDK only and is checked after each response, and its documentation says spend can pass it. onbudget checks before each request and also works in a terminal session.
• The <total_tokens> countdown is undocumented and set by the server, padded to 15 million tokens. It has been in Claude Code builds since at least 2.1.200, on by default since at least 2.1.235, and 2.1.304 sends it only for models with a certain capability. It is not a task budget; while a budget is open onbudget leaves it out of new requests (see How it works).
• The warning at 85% of the session limit tells you; onbudget acts on the model's requests.
• Auto-continue at a reset (2.1.234 and later) carries on after the limit resets; a budget does not grow at a reset.
• The Wrap-Up Allowance lets a response in progress finish at the 5-hour limit. It is rolling out gradually and does not apply to API keys. onbudget stops before either limit, including the weekly one, where the allowance does not apply.
• A near-limit note ("Claude will wrap up the current step") has been in the binaries since 2.1.250 behind a flag; onbudget's meter tells the model what is left throughout.
• The hidden --task-budget flag and the SDK's taskBudget (alpha) set an API-side budget in tokens; onbudget does not use them.
• None of these gives a task a budget in an interactive session, and none acts at the weekly limit.

Other plugins

Budgets on the weekly window already exist: redline (sankalpgunturi/redline, 80% 7d), markwpearce/rainy-day-plugin, nikhilsitaram/claude-caliper's usage-guard (--window 7d, stopping at 99% by default), MohammadMD1383/claude-usage-plugin and michael-L-i/agent-budget. HeyCubit/effortless lowers effort near the limit. ccdwyer/budget-governor (a mod), cost-guard and budgetclaw cap dollars in interactive sessions. They enforce by locking tools, blocking prompts, ending the process (Keesan12/martin-loop) or proxying the API (metahumansworld/SIwithin). As far as both Anthropic marketplaces and a GitHub search showed on 2026-10-21, onbudget is the only one that refuses the individual model request from inside Claude Code, and the only one that publishes an evaluation with its raw data.

Install

onbudget needs Claude Code 2.1.287 or later: from that release the mods API it is built on (function hooks in plugins) is on by default. Its test suites passed on Claude Code 2.1.288, 2.1.304 and 2.1.306 on macOS; GitHub Actions runs the validations, the in-engine tests, run.py and wire.py on Linux with the release current at each push.

claude plugin marketplace add sebastiandrazsky/onbudget
claude plugin install onbudget@onbudget

Inside a Claude Code session the same two commands start with /plugin instead of claude plugin. To stay on this release until you choose to move, add the marketplace pinned to its tag instead:

claude plugin marketplace add sebastiandrazsky/onbudget#v0.1.2

From a local checkout, for one session: claude --plugin-dir /path/to/onbudget.

Type /onbudget. It should answer onbudget: no budget is set and name its version and the Claude Code builds it was tested on.

When onbudget is not running, there is no budget

Nothing outside the plugin enforces a budget. If the plugin does not run, requests are neither metered nor refused, and ONBUDGET is ignored, so a headless task runs with no budget at all. That happens when Claude Code starts in safe mode (--safe-mode) or --bare mode, which load no plugins; when an organisation's managed settings turn plugins or mods off; when Anthropic switches the mods API off; and when Claude Code unloads the plugin (see "The hooks worker" under Limitations). A plugin that runs before onbudget can also skip its hooks; from 2.1.304 the transcript names the plugin and the event when it does. A request whose hook does not run is not checked, though its cost is in the ledger the next check reads. A hook that runs and fails, or runs out of time, is different: while a budget is set, the request is not sent, and the plugin says so ([onbudget] Not sent: the budget check could not be completed).

How to tell. In a terminal session, /onbudget is offered when you type /onb, and once a budget is set a status line under the prompt shows the tier and what is left. Without the plugin, /onbudget is not offered and, typed anyway, is sent to Claude as an ordinary prompt. In a headless run, claude -p "/onbudget" prints onbudget: no budget is set without a model request when the plugin is running. To check one particular run, start it with ONBUDGET_LOG=1: as the session starts, the plugin writes log/events.jsonl in its own folder, beginning with a session.start row. For an install from the marketplace that folder is plugins/cache/onbudget/onbudget/0.1.2 under your Claude config directory. Delete the file before the run; if the run does not write it again, the plugin did not run.

Use

A dollar budget

/onbudget $3 Implement authentication

The task is sent with a short protocol appended, which you can read in the transcript: the budget, how to work under it, and how to report at the end. From then on:

• A status line under the prompt shows the tier, what is left before the stop and the budget, for example onbudget: tier MEDIUM · $1.60 left · budget $3.00. When one of the account's windows is closer than the budget it is named, as in tier HIGH · $61.16 left (5h limit) · budget $500.00. Under a budget counted in points the figures are points, as in tier HIGH · 78 pts left · budget 81 pts (week), and a budget that has stopped reads STOPPED · $2.91 of $3.00 · /onbudget off. /onbudget gives the full reading.
• After each tool result Claude is shown the meter, a longer line with the same figures: [budget] spent $1.23 of $3.00 | left before the stop $1.60 (53%) | tier MEDIUM. "Left before the stop" is exactly what the stop rule still allows, so the meter and the status line read $0.00 when the next request will be refused.
• Reasoning effort is capped at medium while the budget is set. Your setting comes back when the budget is removed.
• When Claude ends the task with its STATUS line, the plugin adds a line of its own in a terminal session: how the task ended, the spend against the budget, how many whole points each usage window moved, and that the budget is still open. Under a budget counted in points it gives the points the window moved against the points budgeted, and the task's own spend in dollars apart.

Follow-up prompts draw on the same budget. Once the budget has stopped the session, a further prompt is turned away with the reason, and nothing is spent on it. /onbudget off removes the budget, and /onbudget <budget> <instructions> replaces it with a new one.

A share of a usage window

/onbudget 10% 5h Build this application
/onbudget 5% week Fix these bugs

A 5-hour point is worth a different number of dollars on every plan, so onbudget learns the rate from your own usage: in every session where the plugin is loaded it records how far each window moved and how much the session cost. A 5-hour percentage budget set after it has seen three points of movement is converted into dollars at that rate, and the dollars are enforced as a dollar budget is. Before a rate is known, the budget is enforced on the window reading itself, in whole points, with a 3% minimum. /onbudget shows the rate.

A weekly percentage budget is always enforced on the weekly window's own reading, in whole points, with a 3% minimum, unless you set usdPerPointWeek (see Configuration): the weekly rate onbudget learns errs far low (see Limitations), and converting with it would have given at most about two fifths of the share named.

What a window has left

/onbudget 5h Refactor the parser
/onbudget week Write the migration

The budget is the points between the window's reading and 99% when you give the command. For 5h they are converted to dollars when a rate is known; for week, only when you have set usdPerPointWeek. Otherwise the budget is counted in the window's own points, and onbudget stops about two points short of 99%, because the reading may not yet show the last requests. onbudget keeps one point back from the account's limit because a reading can be up to a point below the true figure. A session with no reading yet (a new session, or a headless run) sizes the budget from the first one, which arrives with Claude's first answer, so that first request goes out before the budget is known. If the window resets while the task runs, the budget stays what it was when you set it.

Every budget is also bounded by what the account has left

The meter follows whichever comes first, the budget or one of the windows, and names the window when it is the closer one: left before the stop $0.40 (17%), set by the account's 5-hour limit. The status line marks it (5h limit). A budget larger than what a window has left says so when you set it and runs against the window. A window with nothing left refuses the budget in one line, and a new session that has no reading of its own uses the last reading seen on this machine for that check, as long as that window has not reset since.

Accounts that report no usage window (an API key, a gateway) have no such limits: dollar budgets work as described, and budgets counted in a window cannot be enforced. A gateway's own spend limit, which Claude Code also reports, is not used.

Headless runs

ONBUDGET='$3' claude -p "Implement authentication"
ONBUDGET='5h' claude -p "Build this application"

ONBUDGET applies to the first prompt of the session, once. If the value cannot be used, the prompt is dropped with the reason; the task is not run without its budget. When the budget stops a headless run, the run's result is the plugin's notice, which begins [onbudget] Stopped:. In claude -p, set the budget with ONBUDGET: the form claude -p "/onbudget <budget> <task>" sets the budget but can exit before the task is sent (exit code 0, nothing run, nothing spent), a known issue in 0.1.0 to 0.1.2.

How it works

The ledger. Spend is the growth of the session's own cost ledger since the budget was set. Each request is charged the ledger's growth since the previous request completed, and no more than its growth since the request was sent, so a request is not charged for the ones that ran beside it or for what was spent between requests. Two requests that finish at the same instant cannot be told apart: the first to read the ledger is charged both, the total stays exact, and the reserve errs high.

The stop. A request cannot be priced before it is sent, so the plugin holds back what the dearest request so far has cost: refuse when spent + reserve × (requests in flight + 1) ≥ budget. A window of the account is a limit of the same shape. With a rate, its room is converted into the task's dollars from the reading that came with the latest answer; without one, each request is reckoned to move the window by a point, or by the largest step seen between two readings.

The meter. Claude is told the budget once, with the task, and shown the meter after every tool result. The tier is HIGH from 70% left, MEDIUM from 30%, LOW from 10%, and CRITICAL below that or when two requests' worth or less is left at the cost of the dearest so far (two points, for a budget counted in points). Claude has therefore read CRITICAL at least twice before a request can be refused, on one condition: requests one at a time, none costing more than the dearest before it. At small budgets that condition often fails. In the acceptance of 2026-10-21, the three live runs that came near the stop ($0.12, $0.15 and $0.25, on Claude Code 2.1.304 with Claude Opus 5.5) each read CRITICAL once, not twice, because a request cost more than any before it; none passed its budget. The protocol asks Claude to stop adding scope at LOW, to leave the tree in its best verified state at CRITICAL, to verify before it claims anything, and to end with what is complete, what is unfinished and what was not verified. After a compaction the protocol is sent again.

The status line. It is for you; Claude reads the meter, not this line. Claude Code cuts a plugin's status line at the terminal's width: after onbudget: it shows the width less 17 characters, 63 in an 80-column terminal (measured on 2.1.304 and 2.1.306). onbudget's line is at most 60 characters, its fields in order of importance (the tier, what is left before the stop, the budget, and the account limit when one is closer), so it shows whole from 77 columns, and in a narrower terminal the budget is cut first.

Claude Code's countdown. While a budget is open, onbudget leaves Claude Code's <total_tokens> countdown out of new requests, because it is not the task's budget. This is partial: the copy in the system prompt stays. Its effect on the model was never measured. An attachment already sent keeps the answer it was sent with, and a resumed session gets the same answers again, so the prompt cache's prefix does not change. A countdown under a million tokens could be a budget you set yourself, and is kept; so is any countdown when CLAUDE_CODE_TOTAL_TOKENS_REMINDER is set.

Effort. Each request's effort is lowered to the cap and never raised. Nothing in your settings is changed, so there is nothing to restore.

What it reads, writes and changes

PRIVACY.md says the same as a privacy statement, with what the event log records.

claude plugin validate --strict .claude-plugin/plugin.json lists every engine call the plugin can make:

./register.ts calls: $.clock.after (via submitLater), $.clock.now, $.command.register, $.env.get (via load), $.fs.exists (via log), $.fs.write (via log), $.prompt.submit (via submitLater), $.session.id, $.session.model (via calModel, rateFor), $.session.usage, $.session.version, $.store.delete, $.store.get (via calModel, load, otherRecords, prune, startReadings), $.store.keys (via otherRecords, prune), $.store.set, $.ui.log (via say), $.ui.status (via showStatus)
./register.ts env writes: nothing
./register.ts env reads: CLAUDE_CODE_TOTAL_TOKENS_REMINDER, ONBUDGET, ONBUDGET_LOG

What it reads

• The session's cost ledger and the usage-window readings Claude Code reports, the session's id and model, Claude Code's version, and its own store.
• Three environment variables. None is a secret, and none holds a credential:
• ONBUDGET: a budget for the first prompt of a headless run (ONBUDGET='$3' claude -p "..."). A budget for one run is not something to save as a setting, so it stays a variable.
• ONBUDGET_LOG: 1 turns on the event log (below); off when unset, and any other value leaves it off.
• CLAUDE_CODE_TOTAL_TOKENS_REMINDER: Claude Code's own setting, read only to respect it. When you have set it, onbudget keeps Claude Code's token countdown in requests instead of leaving it out.

The effort cap and the dollars per point are options (see Configuration), not variables.

What it writes

• Its store. One JSON file under your Claude config directory, plugins/store/onbudget_*.json: the budget of each session that has one, with the first line of its task (at most 120 characters, shown by /onbudget), calibration records (dollars spent and points moved per session, window and model, nothing else), the newest reading of each window with its reset time, and, per budgeted session, which countdowns it left out, with the day it last went through other sessions' records. Records older than 30 days are deleted when a session starts: calibration records at every start, other sessions' budgets and flags at the first start of each day.
• The event log, off by default. With ONBUDGET_LOG=1, one JSON-lines file in the plugin's own folder, log/events.jsonl, continued in log/events.1.jsonl, log/events.2.jsonl, ... every 200 rows. Each Claude Code process that logs starts it again. The path is fixed in the code: no variable or setting can point it anywhere else. It stays until you delete it.
• Display only. The status line under the prompt, and lines in the transcript that Claude does not read: the line under Claude's STATUS line, the note when another plugin raises the effort, and the answers to /onbudget.

It writes nothing else: no build, start-up, settings or instructions file, and nothing in your project.

What it adds to the prompts it submits

<!-- readme.py: prompts --> Only while a budget is set. These texts are rendered