Spend limits
Cap what an agent, a task, a parent task's subtasks or a workspace can spend per day, month or life, and see what happens at each cap and what warns you.
Beyond visibility into what you’ve spent, CodeHerder can actively cap spend before it grows unchecked. There are seven spend controls, and they stack: an account-wide cap on one agent’s daily spend in each workspace, an account-wide default cap on a task’s total spend, a budget on one specific task that overrides that default, a cap on a parent task and all its subtasks together, and three caps on a whole workspace (a lifetime budget, a daily cap and a monthly cap). Five of the seven warn you before they bind: the agent daily cap (see Notifications below), a task or workspace lifetime budget (see Warnings before a cap binds below), and the workspace daily and monthly caps (see Daily and monthly workspace caps). The account-wide default cap and the subtree cap are the exceptions — nothing warns a human before they bind, though the working agent may still get a spend notice on the way there. See Plans and limits for how account-level plans work.
All seven 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.
Usage covered by an AI subscription plan never counts toward any cap. Every cap compares only spend that is billed directly, so the total in a task’s spend row can be higher than the figure it’s measured against. See Billed vs. covered.
CodeHerder’s own analyst sessions (retrospectives and Evaluation assessments) carry one more cap of their own, on top of these seven — 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 lifetime budget still stops those sessions along with every other live session in the workspace, and a workspace daily or monthly cap still refuses new spawns for them.
At a glance
| Control | Caps | Scope | Where you set it | When reached |
|---|---|---|---|---|
| Agent daily spend cap | One agent’s spend in one workspace for the current UTC day | One value for the account, counted separately in each workspace | Settings → Plan & usage → Spend caps | That agent can’t start new work in that workspace until the day rolls over or the cap is raised. Other agents, and the same agent in other workspaces, are unaffected. |
| Default task spend cap | A task’s total spend, for life | Account-wide, unless the task has its own budget | Settings → Plan & usage → 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. |
| Subtree spend cap | A parent task plus every subtask beneath it, for life | One parent task | ch task edit --subtree-budget or the API (see below) |
No task in the branch starts a new session. Running sessions continue and no task is blocked. |
| Workspace lifetime budget | That workspace’s total spend, for life | One workspace | Settings → General → Spend cap, or the API (see below) | Every live session in the workspace stops, and every open task in it moves to blocked. |
| Workspace daily cap | That workspace’s spend in the current UTC day | One workspace | Settings → General → Spend cap, or ch workspace edit |
New agent spawns in the workspace are refused until the next UTC day. Running sessions keep going and no task is blocked. |
| Workspace monthly cap | That workspace’s spend in the current UTC month | One workspace | Settings → General → Spend cap, or ch workspace edit |
New agent spawns in the workspace are refused until the next UTC month. Running sessions keep going and no task is blocked. |
All seven controls need the Pro plan. This includes a task’s own budget and a subtree cap. Without it, the Spend caps section on the Plan & usage page shows the prompt “Budget spend caps — available on the Pro plan.” above the fields, which may include a Contact sales to upgrade link, and a request to set a workspace cap, a task’s own budget or a subtree cap is refused with feature_not_entitled. A budget you set earlier stays enforced if your plan changes. See Plans and limits.
Your task’s effective ceiling
A task can have up to six spend limits pointing at it at once: its own budget, a subtree cap on itself or on any parent above it, its workspace’s lifetime budget, its workspace’s daily cap, its workspace’s monthly cap, 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 limit is measured against the workspace’s spend, and a subtree cap against the branch’s spend, not the task’s own, so a task that has spent almost nothing can still be the one that trips one of those caps.
ch task show <taskId> prints a spend row that always tells you where a task stands, in shapes like these:
spend: unknown · no budget set
spend: $0.12 total · no budget set
spend: $4.10 of $5.00 (82% used · ceiling: task)
spend: $12.40 of $25.00 (50% used · ceiling: subtree cap of task 0190f3a2-5c4e-7b1d-9a8f-2e6c4d1b7a90)
spend: $0.12 total · workspace $84.00 of $100.00 (84% used · ceiling: workspace)
spend: $0.12 total · workspace today $18.00 of $25.00 (72% used · ceiling: workspace_daily)
spend: $0.12 total · workspace this month $210.00 of $300.00 (70% used · ceiling: workspace_monthly)
no budget set doesn’t mean a cap is close — it means none of the levels applies to this task at all: no task budget, no workspace limit, 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 lifetime budget is, ceiling: workspace_daily and ceiling: workspace_monthly mean the workspace’s daily or monthly cap is (the row says workspace today or workspace this month), and ceiling: plan_default means the account-wide default is. ceiling: subtree cap of task <id> means a subtree cap is the closest, and it names the parent task that carries the cap. In that row the amount spent is the whole branch’s billed spend, not the task’s own. The percentage is calculated for you — trust the number in the row rather than dividing spend by budget yourself, since a workspace or subtree ceiling divides by a wider spend than the task’s own. A workspace limit counts only that workspace’s own spend, not the spend of any workspace beneath it.
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 to a task budget or workspace lifetime budget, each aimed at a different audience. A subtree cap sends no direct message and no forecast, only the notice to the working agent described under What the agent sees. The workspace daily and monthly caps send their own notices, covered in Daily and monthly workspace caps.
The 80% warning
Once a task budget or a workspace lifetime 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 lifetime 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 lifetime budget: any workspace under that 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.
The forecast covers only a task budget and a workspace lifetime budget, not the daily or monthly caps. 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, including a workspace daily or monthly cap or a subtree cap. For a subtree cap, the notice names the parent task that carries it. 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 & usage and find the Spend caps section. It has two fields: Agent daily spend cap (USD per day) and Default task spend cap (USD). Enter a dollar amount for either, or leave a field blank for Unlimited. Only an owner or admin of your account’s top-level workspace can change these settings; everyone else sees them read-only.
How the agent daily cap behaves
The cap is one dollar figure for the account, but CodeHerder counts each agent’s spend separately in each workspace. Once an agent’s spend in a workspace for the current UTC day reaches the cap, CodeHerder refuses to start that agent on new work in that workspace. The agent can still work in other workspaces. The refusal clears 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.
This stop doesn’t block the task. The task keeps its status and shows a Start refused badge, with a Start refusal row naming the cause (the agent has reached its daily spend cap). ch task show <taskId> prints the same as a start refusal row.
How the default task cap 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
A human owner or admin on the Pro plan 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 parent task and its subtasks
A subtree spend cap limits what a parent task and everything beneath it can spend together. Use it when you hand a large job to an agent that splits the work into subtasks and you want one limit for the whole branch. A task’s own budget can’t do that, because it counts only that task’s own spend.
A human owner or admin on the Pro plan can set it from the ch CLI. Amounts are in dollars, and a leading $ is accepted:
ch task edit <taskId> --subtree-budget 25
ch task edit <taskId> --subtree-budget 12.50
ch task edit <taskId> --clear-subtree-budget
You can’t pass --subtree-budget and --clear-subtree-budget together. There’s no field to set it in the web app. An agent session can’t set it. You can also set it through the API: send {"subtreeCostBudgetUsdMicros": 25000000} to PATCH /v1/tasks/{taskId}, where 25000000 is $25.00. Sending 0 clears it.
To check it, run ch task show <taskId>. A capped task prints a subtree-budget row. The task page in the web app shows the same figure as a read-only Subtree spend cap row.
What the cap counts
The cap counts the billed spend of the task itself and of every subtask beneath it, at any depth, including subtasks that live in other workspaces. Usage covered by an AI subscription plan doesn’t count, so this figure can be lower than Total with subtasks on the task page, which counts all spend. See A parent task and its subtasks. CodeHerder reads the branch each time it checks, so if you move a subtask to another parent, its spend moves with it.
What happens at the cap
When the branch’s billed spend reaches the cap, no task in the branch can start a new session. This holds for the capped task and for every subtask beneath it. Nothing else changes: running sessions aren’t stopped, no task moves to blocked, and no blocker is filed. A held task shows a Start refused badge, and ch task show <taskId> prints a start refusal row. For a subtask, the row names the parent task that carries the cap, with the amount spent against the cap.
Because the cap limits new starts, the branch can go past it. A running session finishes its current work, and sibling tasks that start at the same moment can all pass the cap together. Treat it as a limit on starting work, not a hard ceiling.
To resume work, raise the cap or clear it with ch task edit <parentTaskId> --subtree-budget <amount> or --clear-subtree-budget. Held tasks start again on the next scheduler pass, and there is nothing to unblock by hand.
Capping a whole workspace
An owner or admin can cap the spend of an entire workspace in three ways: a lifetime budget, a daily cap and a monthly cap. All three count only that workspace’s own billed spend, not spend in any workspace beneath it. You set them on leaf workspaces, the ones that hold tasks. Only a human admin can change them, and the plan must include spend caps.
In the web app, open Settings → General in the workspace and find the Spend cap section. It has three rows: Lifetime limit, Daily limit (USD per UTC day) and Monthly limit (USD per UTC month). Leave a row blank to clear it. Without the plan you see an upgrade note, and without the admin role the values are read-only.
The lifetime budget
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 ch flag for the lifetime budget. Set it in the app, or through the API:
PATCH /v1/workspaces/{workspaceId}
{"costBudgetUsdMicros": 500000000}
Sending 0 clears it. This is a lifetime figure that never resets on its own. Once it’s reached, work in that workspace stays stopped until you raise the limit or clear it.
Daily and monthly workspace caps
A daily or monthly cap limits what a workspace spends in the current UTC day or UTC calendar month. It is a gentler lever than the lifetime budget: at the cap, CodeHerder refuses to start new agent sessions in the workspace, and nothing else changes. Sessions already running keep going, and they can take the workspace past the cap before they finish. No task moves to blocked.
Set a cap in the app, as described above, or with ch workspace edit. Amounts are in dollars, and a leading $ is accepted:
ch workspace edit <workspaceId> --daily-spend-cap 25
ch workspace edit <workspaceId> --monthly-spend-cap 400
ch workspace edit <workspaceId> --clear-daily-spend-cap
A cap must be greater than zero. To remove one, use the matching --clear-... flag. You can’t pass a cap and its clear flag together. Check what’s set with ch workspace show <workspaceId>, which prints spend cap (lifetime), spend cap (daily) and spend cap (monthly) rows. A cap that isn’t set reads none.
A task held back by one of these caps keeps its status. It shows a Start refused badge, and ch task show <taskId> prints a start refusal row saying the workspace’s daily or monthly spend cap is reached and spawns resume at the next UTC day or month. There is no blocker to clear. The refusal ends by itself at the rollover, or right away if an admin raises or clears the cap.
Notices
The workspace owner gets a direct message when the day’s or month’s spend reaches 80% of the cap (the default — a self-hosted deployment can change it), and another when it reaches 100%. Each message arrives once per day or month, not every few hours.
Reading the blocker
When a task budget or a workspace lifetime budget 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:
taskmeans either the account’s default cap or that task’s own budget was reached. Runch task show <taskId>and check theceiling:value in itsspendrow:taskmeans that task’s own budget stopped it,plan_defaultmeans the account-wide default did.workspacemeans the workspace’s lifetime 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 default task cap, task budget, or workspace lifetime budget gets its own set of warnings on the way to being reached — see Warnings before a cap binds above. The workspace daily and monthly caps send the owner notices described under Daily and monthly workspace caps. A subtree cap sends no direct message to a person. Once a cap that blocks tasks is actually reached and a task is blocked, CodeHerder notifies everyone watching that task with notifications set to status changes or all, 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 labeled “Today in this workspace vs. daily cap”, read as $spent / $cap (or $spent / Unlimited). An All workspaces you can see row below it is for information only; the cap applies per workspace. ch task show <taskId> shows a task’s own spend row against its effective ceiling (see Your task’s effective ceiling above). A task with a subtree cap also has a subtree-budget row there. A task stopped by a task budget, the default task cap or a workspace lifetime budget shows status blocked — check ch task blockers <taskId> to see why. A task held back by an agent’s daily cap, a subtree cap or a workspace daily or monthly cap isn’t blocked; look for the Start refused badge instead.
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
Last updated