Task & Project Budgets

RoboCo can cap real dollar spend two ways at once: a monthly ceiling per project (claim-time) and a hard ceiling per task (checked while work is running). Both are off by default — flip ROBOCO_TASK_BUDGETS_ENABLED and neither cap is ever consulted regardless of what's set in the project or task fields.

Project monthly budget

Set a Monthly Budget (USD) on a project (the project's settings page, Budget & Ops card) — like the task field below, a 0 is rejected (leave it blank for no cap; a 0 would block every claim outright). Once this calendar month's summed agent-spawn spend across the project's tasks reaches that figure, a new work-starting claim (give_me_work → i_will_work_on, or a PM's i_will_plan) is refused.

In-flight work always finishes

The claim guard only applies to claims that start work. Review, documentation, gate, and inbound-PR-review claims are exempt — a task already moving through QA, docs, or the PR gate can always finish, even if the project crossed its cap mid-flight. The cap only stops new work from starting against an over-budget project.

The refusal names the exact cap and this month's spend, and tells you to either wait for next calendar month or raise the project's Monthly Budget field.

Task budget

Set a Budget (USD) on an individual task (create/edit task dialog). A 0 is rejected outright — it would silently block everything, which is never what you meant. Leave it blank for no cap — this field is explicit-input only. There is no per-TaskType fallback figure; a blank budget means the sweep below never fires for that task, however long or expensive it runs.

A background sweep prices the active task's own spend (closed-session cost plus live-token pricing on any open session) against this cap, whenever one is set. On breach:

  • The task is blocked — status BLOCKED, resolver type HUMAN — before the agent is stopped, so the graceful shutdown's own unclaim finds the task already blocked and never bounces it back through pending for an instant re-claim that would just re-burn the same budget.
  • You get a notification naming both recovery steps: raise the task's budget, or let it stay blocked.
  • unblock re-checks live spend before releasing a budget-blocked task — it refuses again while spend is still at or over the (possibly still-unraised) cap, so there's no silent re-breach loop where unblocking just walks straight back into the same wall.
This blocks, it doesn't kill

A budget breach is a deliberate stop for your decision, not a race to prevent one more token from being spent — the sweep runs on its normal interval, not instantaneously. Set a figure that gives a well-scoped task real headroom, not a precise cutoff.

Enable it

Settings → Feature Flags carries "Task & project cost budgets". Flipping it takes effect on the next backend restart, same as every other flag on that card.

bash
1ROBOCO_TASK_BUDGETS_ENABLED=true
Different defaults per compose file

docker-compose.yml (the personal/NAS deploy) arms this on by default; docker-compose.registry.yml leaves it off, matching that file's safe-default posture for a fresh third-party deploy.

Next

→ Cost & usage for the spend the sweep prices against · Workstation for the project settings page · Tasks & Kanban for the task dialog · back to Optional subsystems.

llms.txt