Run from a terminal
Run a team from its file with one command, see what happens as it happens, and use the exit code in scripts.
A team file runs without the app: sculptured run starts the team on this computer, prints a line whenever an agent starts working, finishes a turn, asks something or stops, and ends with an exit code that says how it went.
sculptured run review-team.madl.yaml --folder ./my-project
Export team file (the team's Settings → Export) saves a file that also runs on its own:
chmod +x review-team.madl.yaml
./review-team.madl.yaml --folder ./my-project
Its first line, #!/usr/bin/env -S sculptured run, is a comment to every other tool, so the file is still an ordinary MADL file.
Options
| Option | What it does |
|---|---|
--folder DIR | Where the agents work (default: the current folder). Agents with a folder of their own keep it. |
--input-text TEXT | The team's Input. |
--tokens N, --minutes N | The run's budget. They can only lower what the file sets; a higher value is refused. |
--data-dir DIR | Where the run's records go (default: ~/.sculptured/runs/<name>-<time>). |
While it runs
- Questions are asked in the terminal: type the answer, or the number of an option. Without anyone at the terminal (a script, a job), the run stops and prints what was asked.
- Ctrl+C asks every agent to wrap up; press it again to stop them at once. Closing the terminal or
killstops them at once too. - The run is over when every agent has stopped, or when every agent has finished its turn with nothing waiting for 20 seconds. Then the team is stopped and the runner it started ends.
Exit codes
| Code | Meaning |
|---|---|
| 0 | Every agent finished |
| 1 | An agent's turn failed, or the team could not start (the reasons are printed) |
| 2 | A budget stopped the run |
| 3 | An agent asked something and no one was at the terminal to answer |
| 4 | The file is not valid (its MADL errors are printed) or an option is |
| 130 | Stopped with Ctrl+C or asked to end |
Inside a cluster job
A batch job can run a team: the job ends the run when its time is up, and the agents wrap up first if --minutes leaves room (a lowered limit starts the wrap-up at 85% of it). Run it with exec, so the scheduler's stop signal reaches sculptured run directly. The compute node needs to reach Anthropic or OpenAI (check with sculptured doctor), and Claude Code or Codex signed in for your account; ask your site whether agents may run in jobs.
Slurm
#!/bin/bash
#SBATCH --job-name=review-team
#SBATCH --time=02:00:00
#SBATCH --signal=B:TERM@120
exec sculptured run review-team.madl.yaml --folder "$SLURM_SUBMIT_DIR" --minutes 110
--signal=B:TERM@120 asks the job to stop two minutes before its limit, so the run stops cleanly rather than being killed.
PBS
#!/bin/bash
#PBS -N review-team
#PBS -l walltime=02:00:00
cd "$PBS_O_WORKDIR"
exec sculptured run review-team.madl.yaml --folder "$PBS_O_WORKDIR" --minutes 110
At the walltime PBS sends the job a stop signal before killing it; --minutes 110 has the agents wrap up before that.
The exit code tells the next step of a pipeline what happened (see Exit codes).