Spend limits

Beyond visibility into what you’ve spent, CodeHerder can actively cap spend before it grows unchecked. There are four spend controls, and they stack: an account-wide cap on one agent’s daily spend, an account-wide default cap on a task’s total spend, a budget on one specific task that overrides that default, and a budget on a whole workspace. Three of the four warn you before they bind: the agent daily cap (see Notifications below), and a task or workspace budget (see Warnings before a cap binds below). The account-wide default cap is the exception — nothing warns a human before it blocks a task, though the task’s own working session may still get a spend notice on the way there. See Plans and limits for how account-level plans work.

All four act on recorded spend. A turn that runs on an unpriced model reports its token counts with no dollar figure, so it can’t push a cap over the line by itself — see Choosing the coding-agent CLI your agents run for when that happens.

CodeHerder’s own retrospectives and prompt trials carry one more cap of their own, on top of these four — see The optimization budget. It’s an addition, not a substitution: an agent’s daily cap still gates the agent that runs that work, and a workspace budget still stops those sessions along with every other live session in the workspace.

At a glance

Control	Caps	Scope	Where you set it	When reached
Agent daily spend cap	One agent’s spend for the current UTC day	Account-wide	Settings → Plan → Spend caps	That agent can’t start new work until the day rolls over or the cap is raised. Other agents are unaffected.
Task total spend cap (default)	A task’s total spend, for life	Account-wide, unless the task has its own budget	Settings → Plan → Spend caps	The task’s active sessions stop and it moves to blocked.
A task’s own budget	That one task’s total spend, for life	One task	The API (see below)	Same as the default cap: sessions stop, the task moves to blocked.
A workspace’s own budget	That workspace’s total spend, for life	One workspace	The API (see below)	Every live session in the workspace stops, and every open task in it moves to blocked.

The account-wide caps and the workspace budget need the Pro plan. Without it, the Spend caps fields on the Plan page show read-only, above a prompt to contact sales, and a request to set a workspace budget is refused the same way. Setting a task’s own budget carries no such gate by itself, but you still need an API key to call the API at all, and minting one for a person needs the Pro plan too — see Plans and limits.

Your task’s effective ceiling

A task can have up to three spend limits pointing at it at once: its own budget, its workspace’s budget, and the account-wide default for a task’s total. When more than one applies, CodeHerder doesn’t just take the smallest dollar figure — it takes whichever one the task is closest to hitting, measured as a percentage. That matters because a workspace budget is measured against the workspace’s total spend, not the task’s, so a task that has spent almost nothing can still be the one that trips a workspace cap.

ch task show <taskId> prints a spend row that always tells you where a task stands, in shapes like these:

spend: no spend recorded · no budget set
spend: $0.1200 total · no budget set
spend: $4.1000 of $5.0000 (82% used · ceiling: task)
spend: $0.1200 total · workspace $84.0000 of $100.00 (84% used · ceiling: workspace)

no budget set doesn’t mean a cap is close — it means none of the three levels applies to this task at all: no task budget, no workspace budget, no account-wide default. As soon as any level does apply, the row names it, at whatever percentage spend has actually reached — a task at 2% of its own budget still prints ceiling: task, not no budget set. ceiling: task means the task’s own budget is the one that’s closest to being hit, ceiling: workspace means the workspace budget is, and ceiling: plan_default means the account-wide default is. The percentage is calculated for you — trust the number in the row rather than dividing spend by budget yourself, since a workspace ceiling divides by the workspace’s total spend, not the task’s.

ch costs task <taskId> shows the same thing as a trailing lifetime: line, alongside that task’s cost breakdown — see Understanding costs for the rest of what that command prints.

Warnings before a cap binds

CodeHerder doesn’t wait until a cap is reached to say something. Three separate warnings fire on the way there, each aimed at a different audience.

The 80% warning

Once a task budget or a workspace budget reaches 80% of its limit (the default — a self-hosted deployment can change it), CodeHerder sends a direct message to the owner — the workspace owner for a workspace budget, or the task’s owner for a task budget. Nothing stops: sessions keep running, and the task stays wherever it is in its workflow. It’s a heads-up, not an action, and it repeats at most once every six hours for as long as spend stays in that 80–100% band, so you won’t get a DM every few minutes.

The forecast warning

Alongside the 80% warning, CodeHerder projects when a budget is likely to be reached at its current rate of spend and warns you ahead of time — at roughly 48 hours out, and again at roughly 12 hours out if spend is still climbing. This one never stops or blocks a task either; it only tells you what’s coming.

• For a workspace budget: any workspace under its budget is checked, using its average daily spend over the last 7 days. The warning goes to the workspace owner.
• For a task budget: a task is only checked once its own spend has reached 80% of its budget, and only if it has recorded spend in the last 24 hours — a burn rate needs recent activity to project from. The warning goes to the task’s owner, and to any watcher whose task notifications are set to all.

Either way, the message names the projected horizon (for example, “~2 days” or “~9 hours”), the daily burn rate, and where spend stands against budget. Like the 80% warning, each horizon repeats at most once every six hours while it still applies.

What the agent sees

While a task has a live session working it, CodeHerder also keeps the agent itself informed: a notice lands in that session when spend crosses 50%, 80%, and 100% of the task’s effective ceiling — the same ceiling the spend row above names. Only the highest band reached fires, so a task that jumps straight from quiet to 100% produces one notice naming 100%, not three. The notice names the percentage, spend against the ceiling, and points the agent at ch costs task <taskId> for the full picture. This needs a running session on the task and a ceiling to measure against; without either, it stays silent.

Setting the account-wide caps

Open Settings → Plan and find the Spend caps section. Enter a dollar amount for either cap, or leave a field blank for unlimited. Only owners and admins can change these settings.

How the agent daily cap behaves

Once an agent’s spend for the current UTC day reaches its cap, CodeHerder blocks that agent from starting new work. The block clears automatically at the next UTC day rollover, or immediately if you raise the cap. A different agent under its own cap can still pick up the same task, so this slows one agent down rather than stalling the task.

How the task total cap (default) behaves

Once a task’s lifetime spend reaches the default cap, CodeHerder stops its active sessions and moves the task to blocked with a note explaining why. Those sessions end with a Released outcome, not a failure (see Sandbox state vs. a run’s outcome). This default only applies to a task that doesn’t already have its own budget — see below.

Giving one task its own budget

An owner or admin can set a lifetime spend limit on a single task, overriding the account’s default for that task alone — higher or lower. There’s no field for this in the web app yet, and no ch flag. Set it through the API instead:

PATCH /v1/tasks/{taskId}
{"costBudgetUsdMicros": 5000000}

Amounts are in USD micros, so 5000000 is $5.00. This is a lifetime figure for the task, not a daily one, and it never resets on its own. Sending 0 clears the task’s own budget, and it falls back to the account default again.

Once set, ch task show <taskId> prints it as a cost-budget row so you can confirm what’s in effect. When the task’s lifetime spend reaches this figure, CodeHerder stops its active sessions and moves it to blocked, the same way the default cap does.

Capping a whole workspace

An owner or admin can also set a lifetime spend limit on an entire workspace. This is a much bigger lever than the other three: reaching it stops every live session in that workspace, not just one task’s, and moves every one of its open tasks to blocked. On a workspace with a lot of open tasks, CodeHerder needs more than one pass to park them all, so don’t be surprised if tasks stop in batches over several minutes rather than all at once.

There’s no web app field or ch flag for this yet either. Set it through the API:

PATCH /v1/workspaces/{workspaceId}
{"costBudgetUsdMicros": 500000000}

Sending 0 clears it. Like a task’s own budget, this is a lifetime figure with no daily or monthly reset — once it’s reached, work in that workspace stays stopped until you raise the limit or clear it.

Reading the blocker

When a spend cap stops a task, ch task blockers <taskId> --active shows a reason starting with cost budget exceeded (task): ... or cost budget exceeded (workspace): .... The word in parentheses tells you the scope that was hit:

• task means either the account’s default cap or that task’s own budget was reached. Run ch task show <taskId> and check the ceiling: value in its spend row: task means that task’s own budget stopped it, plan_default means the account-wide default did.
• workspace means the workspace’s own budget was reached, and every task in that workspace is affected, not just this one.

CodeHerder checks spend on a periodic pass rather than the instant a cost lands, so a task or workspace can run slightly over its cap before work actually stops.

See Spend cap reached in Why isn’t my task moving? for how to resolve any of these.

Notifications

When an agent approaches its daily cap (around 80% of the limit), CodeHerder sends a direct message to the person who operates that agent, and another when the daily cap is reached — so a daily cap is rarely a surprise. A task-total, task, or workspace budget gets its own set of warnings on the way to being reached — see Warnings before a cap binds above. Once any of them is actually reached and a task is blocked, CodeHerder notifies everyone watching that task with notifications set to status changes, plus the task’s owner if they aren’t already one of those watchers.

Where you see it

Each agent’s detail page shows a Spend meter comparing “Today vs. daily cap” as $spent / $cap. ch task show <taskId> shows a task’s own spend row against its effective ceiling (see Your task’s effective ceiling above). A task stopped by a spend cap shows status blocked — check ch task blockers <taskId> to see why.

Related guides

• Plans and limits — what else your account’s plan covers, and where the Plan page lives
• Understanding costs — how spend is tracked and how to view it, including cost-aware model routing (on by default for new workspaces) as a lower-spend alternative to a hard cap
• Choosing the coding-agent CLI your agents run — how spend reporting differs by harness
• Monitoring your agents — fleet health and first-pass rate
• Why isn’t my task moving? — includes what to do when a spend cap blocks a task