Budgets and limits
Keep a run within a share of your Claude or Codex plan, a token count or a time, with a soft value that wraps up and a hard value that stops.
A run of a big team can use a lot of your plan quickly: every agent re-reads its context at every step, and agents can start helpers. A run budget keeps one run within what you choose, for example 30% of your Claude 5-hour window. Agent limits do the same for one agent and the agents it starts.
Every budget and limit has two values:
- Soft: no new work starts, and every agent is asked to wrap up with a summary of what it did and what is left.
- Hard: every agent is stopped at once, like pressing Ctrl+C in a terminal. Anything still running two seconds later is ended.
Leave the soft value empty and it is 85% of the hard value. Sculptured sets no budget of its own: nothing is limited until you set it.
stateDiagram-v2
Running --> WrappingUp: "a soft value is reached"
WrappingUp --> Stopped: "a hard value is reached"
Running --> Stopped: "a hard value is reached"
WrappingUp --> Finished: "every agent wrapped up"
Set a run budget
- Open the team's settingsOpen the project's Settings tab and find Run budget.
- Choose what to limitFill in a hard value, and a soft value if you want one, for any of: Claude or Codex, 5-hour window or weekly (a percent of that plan); Tokens (every agent's tokens added together); Time (minutes from Start).
- Limit how many work at onceMost agents working at once keeps the rest waiting for a free slot. Fewer agents at once use your plan more slowly, and a stop reaches fewer agents in the middle of a step.
- StartThe Start confirmation repeats the budget before anything runs.
Pause until the window resets
A plan window refills on a schedule: Claude's and Codex's 5-hour windows five hours after they start, the weekly ones each week. Instead of stopping, a plan budget can pause the run and continue it by itself once the window resets, so work that needs more than one window's share still finishes.
Under Run budget, a plan budget you have set gets At the hard value:
- Stop (as before): every agent is stopped.
- Pause until the window resets: at the soft value, agents stop at a checkpoint and write a short note of what is done and what is next (
.sculptured/notes/<agent>.mdin their folder). At the hard value every agent is stopped, and two minutes after the window resets the agents that were working start again.
Choose how they continue:
| Choice | What happens | Cost |
|---|---|---|
| From their notes (fresh start) | Each agent starts a new conversation with its job and its note. | Small: its context starts small again. |
| Resume their conversation | Each agent continues its own conversation. | Larger: it re-reads all of it on every step. |
At most sets how many windows the run may use (3 unless you change it); after the last, it stops. Token and time budgets don't refill, so they always stop; time spent paused doesn't count toward a time budget.
While the run is paused, the Run board says until when, and offers Continue now (the run gets a new share of the window it is in), Stop, and the choice of how it continues.
Set an agent's limits
Select an agent and find Limits for one run in its panel. Each row is a soft box, then a hard box:
| Limit | Counts |
|---|---|
| Tokens | The agent's tokens in this run. Choose which kinds count, and whether the agents it starts count too (they do by default). |
| Turns | How many times it has replied to a message. |
| Minutes working | Time spent working, not time waiting. |
At the soft value the agent is asked to wrap up; at the hard value it and every agent it started are stopped at once.
Watch it on the Run board
While the team runs, the bar under the team's controls shows each run budget: how much is used, where wrap-up comes and where the stop comes. includes an estimate means part of the number is Sculptured's estimate since the last plan reading; the age of that reading is shown beside it. Agents held back by Most agents working at once are listed under Waiting for a slot.
Raise a limit while the team runs
Each limit on the Run board has Raise. Enter a higher value and choose Raise, or Raise and continue when the run already wrapped up or stopped at that limit: the run goes back to normal and the agents it stopped carry on where they were (an agent still finishing its wrap-up just keeps working). The soft value moves with the hard one, keeping its share.
A raise is for this run only. The team's saved budget stays what you planned; change it in Settings for the next runs.
An agent's own limits work the same way: when one is reached, Agent limits on the Run board lists each agent's token, turn and minute limits, each with Raise.
A cap for the whole computer
Several teams running at once share one plan. On the Computers page, Most agents working at once sets a cap for each computer, across all its teams; more work waits for a free slot, as with a team's own cap, and the card says at most N agents work at once on this computer. Leave it empty for no cap. A team's own cap still applies inside it.
When a budget acts, the bar says which one and why, for example "Wrapping up: Claude 5-hour: 25.6% used, past the run's soft limit of 25.5%".
To stop everything yourself, choose Stop team…, then Stop everything now. Confirm stop team lets each agent close its session first; Stop everything now interrupts every agent and the commands it is running at once.
How the numbers are measured
- Plan percentages come from Claude Code and Codex themselves, which report how much of each window your account has used. They count all your use of that plan, including outside Sculptured, so other work in the same window counts against the run. That keeps you on the safe side.
- Between reports, Sculptured estimates: it learns how much of the window each token uses from the reports so far (or from your last run) and adds the tokens since the last report.
- Tokens are counted as each model call reports them, not only when an agent finishes a reply.
- A new window: if your 5-hour window resets during the run, counting starts again in the new window.
How close to the limit it stops
Claude Code and Codex report usage after each model call, so no tool can promise to stop at exactly 30%. Sculptured always wraps up first, then stops early by about one model call for each agent working at that moment and interrupts at once, so a run usually ends near the hard value; it can pass it by a little when calls are large or plan readings are late. The more agents work at the same time, the larger that margin; Most agents working at once keeps it small. A budget covers one run: starting the team again starts a new count.
Leave out what agents don't need
Every Claude agent starts with your own Claude Code setup unless the team leaves it out: the list of every skill you installed, your plugins' instructions, your hooks and MCP servers. Each agent re-reads all of it on every model call. Team Advanced → Claude Code setup for agents has two switches:
| Switch | Covers | Default |
|---|---|---|
| Global plugins and settings | your ~/.claude: plugins, skills, hooks, settings, MCP servers | off |
| Project plugins and settings | the agent folder's .claude: its settings, plugins and skills | on |
Sculptured's own agent tools load either way. The setting takes effect the next time an agent starts.
Protections: keep each agent's context small
Most of a long run's tokens are agents re-reading their own conversation on every step, so a conversation that grows large makes every later step expensive, on any model. Team Advanced → Protections keeps it small. It is on by default.
| Protection | Default | What the agent sees |
|---|---|---|
| Refuse reading a whole file larger than | 100 KB | The read is refused with the file's size and the advice to search it with grep -n and read only the lines it needs. Images, PDFs and notebooks are never refused. |
| Shell output an agent sees, at most | 8,000 characters | Longer output is saved to a file; the agent gets its path and a short preview. |
| Continue an agent fresh from its notes at | 60,000 tokens of context | Between turns, the agent is asked to write its notes (.sculptured/notes/<agent>.md), then continues in a fresh conversation from them. A turn is never interrupted. |
Claude agents get all three; Codex agents get the context limit only. Every refusal and every fresh continue shows in the agent's conversation.
When Claude Code compacts a Claude agent's conversation within a long turn, a summary can drop parts of the agent's briefing (its role, its contract, who decides what). With protections on, Sculptured gives the briefing back right after each compaction. An idea from Gas Town. An agent on a computer whose runner predates protections runs without them, and its page says so: reinstall the runner from Computers.
Safety rules
Under Protections, Safety rules refuse tool calls you name, for every Claude agent of the team, with the reason you give. Add a ready-made one, such as no recursive deletes, no reading .env or private keys, no force-push, no piping downloads into a shell, no disk formatting, or write your own:
- Tools: a regular expression over the tool's name (
Bash,Write,Read, …);.*for all. - Conditions: one per line, all must hold, in Signet-Eval's format:
contains(parameters, 'DROP TABLE'),matches(file_path, '\.env$'),param_contains(command, 'sudo'),any_of(…),param_eq,param_ne,not(…),or(A || B).parametersis the whole call; a field name is one part of it.
Sculptured's own guard checks them, with no model call. A rule that cannot be read is shown as a problem on the board and never blocks an agent. For Signet-Eval's own checks as well (its vault, spending limits and locked self-protection), give an agent Signet-Eval policy checks; see Skills and tools.
Contracts: what each agent reads, writes and decides
An agent's Advanced settings include its Contract. Every line is optional:
| Field | What it does |
|---|---|
| Reads / Writes | Files and folders, one per line, relative to the agent's folder. With protections on, Claude agents' Read, Write and Edit calls outside them are refused with the reason. Shell commands are not checked. The agent's own notes folder is always allowed. |
| Other effects | Effects beyond its files, in plain words ("sends email", "pushes to main"), told to the agent |
| Decides | Decisions the agent owns. Every agent is told who decides what, and asks the owner before deciding within its domain |
| Values it shares | Values other agents rely on, such as a port, an endpoint or a field name, one per line as name = exact value @ file. Every start checks each file still contains its value; agents are told what was found, and a value not found is flagged so nobody builds on it. An idea from Constrain. |
| Its decisions reach | Its own work, a group, or the whole team. A decision belongs to the agent whose reach contains its consequences, so a choice that crosses groups goes to that owner instead of being agreed between two agents who are each only locally right |
Contracts travel in MADL files as data_access and authority. MADL also warns when two agents may write the same paths or own the same decision.
Keeping a large team within a small budget
A team of two dozen agents that reads hundreds of PDF pages can use a whole 5-hour window in half an hour. To stay within a third of it:
- Let agents read PDFs as text. The
read_pdftool gives agents a PDF's text and names the pages that need to be looked at as images. Reading pages as images costs far more. - Set Most agents working at once to 6 or fewer, and Most levels of children to 1, in Advanced.
- Split the work into stages across runs, for example reading and planning in one run and building in the next.
- Start fresh rather than resuming when the earlier conversations aren't needed: a resumed agent re-reads its whole earlier conversation on every step.
- Set the budget a little below what you can afford, for example hard 25% when 30% is your limit, because your other use in the same window counts too.
In MADL files
A run budget is written on the system, and an agent's limits in its restrictions. A bare number is a hard value; { soft, hard } gives both:
system:
id: c172
name: C172 model
budget:
plan: [ { provider: claude, window: five_hour, soft: 25, hard: 30 } ]
tokens: { hard: 50000000 }
wall_clock: { soft: 45m, hard: 1h }
max_working: 6
agents:
- id: parser
settings:
restrictions:
budget: { tokens: { soft: 1000000, hard: 2000000 }, turns: 40, working_time: 30m }
See MADL for exporting and importing teams. The design assistant never changes a budget: its proposals keep the run budget and every existing agent's limits as saved.