Sculptured docs

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

OptionWhat it does
--folder DIRWhere the agents work (default: the current folder). Agents with a folder of their own keep it.
--input-text TEXTThe team's Input.
--tokens N, --minutes NThe run's budget. They can only lower what the file sets; a higher value is refused.
--data-dir DIRWhere the run's records go (default: ~/.sculptured/runs/<name>-<time>).

While it runs

Exit codes

CodeMeaning
0Every agent finished
1An agent's turn failed, or the team could not start (the reasons are printed)
2A budget stopped the run
3An agent asked something and no one was at the terminal to answer
4The file is not valid (its MADL errors are printed) or an option is
130Stopped 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).