Agents
AI budget
Each runner shows how much AI it has left, so SpudSuite can do background work for you with capacity that would otherwise go to waste. Nothing that spends money happens unless you turn it on and set a cap.
What a runner can see
Open the runner's page from Runners and find AI budget. Each AI source the runner uses has its own row:
- Claude plan (Pro, Max or Ultra): how much of the 5-hour window and the weekly windows is used, and when each resets. The runner asks Claude Code for its usage report every few minutes. Asking doesn't use any of your plan.
- OpenRouter and LiteLLM gateways: what the key has spent, and its limit when the gateway shares one. For LiteLLM, set
budget: litellmin the gateway'sconfig. - Anthropic API, with an Admin key: what the whole organization has spent this month. Add the Admin key to the runner as a secret named
ANTHROPIC_ADMIN_KEY. Anthropic doesn't share the organization's spend limit, so set your own cap below. - Local models: how many model slots are free.
An ordinary Anthropic or OpenAI API key can't see its balance or limit, so SpudSuite counts what it spends on those itself.
The runner needs to be version 0.1.23 or later. Only shares, dollar amounts and reset times leave the machine, never a key or a sign-in.
Let background work use it
You need to be a workspace admin. Under What background work may use:
- Spare Claude plan capacity: lets background work use what would go unused before each reset. It never spends usage credits.
- Idle local models: lets background work use free model slots. This is on unless you turn it off.
- Keep back for you: the share of each window that background work never touches, so your own Claude Code is never blocked by it.
- As the reset gets closer: how that share changes through a window. Keep it back the whole time holds it flat. Let it go steadily toward the reset shrinks it to nothing by the reset. Hold it until the last fifth, then let it go keeps it until near the end. The small chart shows the curve.
- Pay-as-you-go cap per day and per month: the most background work may spend on API keys and gateways. Leave them empty and it spends nothing on them.
Click Save. Each row then says how much is spare for background work, or why there's none: the source is off, the reserve covers what's left, Claude says the plan is near its limit, or the runner hasn't sent a fresh reading in the last 15 minutes.
Factory's automatic discovery
In a Factory project's settings, Only on spare AI budget makes automatic discovery wait for this budget. On a runner signed in to a Claude plan it runs only while the plan has spare capacity you let background work use. On a runner whose Claude Code uses an API key it runs only while what those runs spent today and this month is under your caps. The project's Overview says what it's waiting for. Factory's other spare-time work, trying next steps on branches and reviewing pull requests, always waits for this budget.
Start workflows from spare budget
Triggers can use the budget too. On a trigger, turn on Only with spare AI budget and choose:
- From: a Claude plan, local models, API keys up to your cap, or any of them.
- Spare above: how much must be spare after the reserve, such as
20%. - Used at less than this of pace:
1means on track to use the whole window.0.8means only when it's running behind, so some would go unused. - Resets within: only near a reset, such as
6h.
In YAML it looks like this:
spec:
event: schedule
schedule: "0 * * * *"
workflow: tidy-backlog
budget:
source: plan
spare_above: 40%
pace_below: 0.8
resets_within: 6h
When there isn't enough, nothing starts and the trigger's Deliveries say why. Fire now always starts a run.
Filters can read the budget as well, such as {{ budget.plan.spare_pct > 30 }}, {{ budget.local.free_slots > 0 }} or {{ budget.metered.allowance_usd >= 2 }}.
When plan capacity is about to go unused
The AI budget card in SpudSuite events raises budget.expiring once per window, when a Claude plan window resets within 12 hours and 20% or more of it is set to go unused. Spare plan capacity must be on for that runner. The event says which runner and window, expiring_pct, spare_pct and resets_in_hours.
A Pro or Max plan belongs to one person. Turn on spare plan capacity only on your own runner.