Spend budgets
Hard period-to-date spend ceilings that gate agent runs: the org ceiling, the workspace ceiling, live burn, and the threshold ladder.
A spend budget is a hard USD ceiling on what an org or a workspace may spend in an accounting period. The platform's billing admission gate enforces it. Once spend exceeds a ceiling, the gate denies every governed action that consumes credits until the period rolls over or someone raises the ceiling.
Two ceilings apply independently:
- The org ceiling covers every workspace in the organization.
- The workspace ceiling covers the active workspace alone.
A run must clear both. The same ceilings back the get_spend_budget and set_spend_budget capabilities, so the CLI, the app, the API, and MCP all read and write one governed record. There is no CLI-local budget.
Read the current ceilings
oxagen budget showFor each configured scope, this prints the ceiling and its live burn: period-to-date spend, a projection to the end of the period, the percent of the ceiling consumed, and whether the gate is denying now.
oxagen budget show --json--json prints the exact contract payload on one line: {"budgets": [...]}, one status per configured ceiling, the org's first. Each status carries scope, publicId, enabled, period, windowDays, limit, spent, projected, ratio, state, reachedThreshold, windowStart, and windowEnd. limit, spent, and projected are money objects that count millionths of a dollar as a string, so a $500 ceiling reads {"micros": "500000000", "currency": "USD"}.
The threshold ladder
state reports where the scope sits now:
| State | Meaning |
|---|---|
ok | Below 50% of the ceiling. |
threshold_50 | Crossed 50%. |
threshold_80 | Crossed 80%. |
threshold_95 | Crossed 95%, the last warning before denial. |
exceeded | At or over the ceiling. The admission gate is denying. |
reachedThreshold records the highest rung crossed in this period, so a notification fires once per rung rather than on every run.
Set a ceiling
oxagen budget set --scope workspace --period monthly --limit 500
oxagen budget set --scope org --period rolling --window-days 30 --limit 5000| Flag | Description |
|---|---|
--scope <org|workspace> | Which ceiling to write. Required. |
--period <monthly|rolling> | monthly resets on the calendar month. rolling uses a trailing window. Required. |
--limit <usd> | The ceiling in dollars. Required. |
--window-days <n> | Trailing-window length. Required with --period rolling, rejected with monthly. |
--enabled <bool> | Turn a ceiling off without deleting it (--enabled false), or turn it back on. |
--json | Machine-readable output. |
set replaces in place. It writes the ceiling for that scope and creates it if absent. Changing a ceiling changes spend behavior, so only these roles can run it: an organization Owner or Compliance and Billing member for either ceiling, and a workspace Admin for that workspace's own.
The CLI checks the rolling and monthly --window-days rule before it sends the request, so a bad combination fails fast with a usage error (exit 2). The platform validates it again regardless.
The no-progress limit
The no-progress limit is the number of identical calls in a row that stop a run counting as progress. An identical call uses the same tool with the same input and gets the same output as the call before it. Every workspace starts at 20 calls in observe mode, which records each run that reaches the limit and lets it go on. Enforced mode also pauses the run before its next step.
oxagen budget no-progress show
oxagen budget no-progress show --from 2026-10-01 --to 2026-10-13show prints the limit in force, the steering PR that waits to change it, and the runs that reached it this month, or over the days you name.
oxagen budget no-progress set --repeats 30 --mode enforced
oxagen budget no-progress set --clear| Flag | Description |
|---|---|
--repeats <n> | Identical calls in a row, 2 or more. Leave it out to keep the count the open steering PR proposes, or the count in force. |
--mode <observe|enforced> | observe records each run that reaches the limit. enforced also pauses it. Leave it out to keep the mode the open steering PR proposes, or the mode in force. |
--clear | Return to the default of 20 calls in observe mode. Send it alone. |
--json | Machine-readable output. |
set writes no setting. It opens a steering PR that changes [limits.no_progress] in workspace.toml, and the limit changes when that PR merges. A second change while the PR is open updates the same PR. If you ask for the limit already in force while the PR is open, set closes the PR instead. Only an organization Owner or a workspace Admin can run it.
Projection vs. observation
oxagen budget show reports what was actually spent: metered usage, the same numbers that reach billing.
To price a workload before it runs, use oxagen cost, which projects token counts against the rate card built into the CLI and makes no network call. To see where the spend on one run went, use oxagen run turns <run-id>.
Command reference
Every oxagen command and flag: spend, prices and billing, steering and repositories, agents and work orders, runs and their evidence, the knowledge graph, the code graph, agent memory, environments, secrets, API keys, and the market router.
Memory from the CLI
Review the memories your agents wrote in their harnesses, ranked by how often runs used them, and promote the ones worth keeping into steering records.