codeflower task

Start a sandbox for a project and let its agent work on TASK by itself, without VS Code, until it is done: for example as a batch job. TASK is the request in plain words, or - to read it from standard input; –prompt FILE reads it from a Markdown file instead.

The agent gets the task as its goal (Claude Code’s and Codex’s /goal) and instructions that nobody is there to answer questions. It works until it judges the task done, or for at most –max-rounds rounds. Its results go to the first –output folder, with a storyteller report, report.html, that it builds as it goes (leave it out with –skip-report). Progress is printed as the agent works.

When the rounds run out, or shortly before –timeout (a tenth of it, between 2 and 15 minutes), the agent is told to stop starting new work and to write up what it did, what it found and what is left, so a stopped task still leaves a report.

The task’s folder, PROJECT/tasks/ID, is printed when the task starts. –continue TASK_DIR runs the task again in the same session: after it was interrupted, failed (e.g. on a usage limit), or ran out of rounds or time, the agent is told so and picks up where it stopped; after it was done, it checks its work again. FOLLOW_UP (or - to read it from standard input) asks for more work in the same task; –prompt FILE reads it from a Markdown file. A continued task keeps its project, agent, folders, network and report; each run gets its own –max-rounds and –timeout, and may choose another –model, –effort, –option, –engine or –image.

–model and –effort choose among what the agent offers, e.g. opus or claude-opus-5 and high for Claude Code, gpt-6.1-sol and xhigh for Codex; the task stops with the agent’s choices when it has no such value. Other settings of the agent go by their id: –option fast=on.

–output-mode auto uses an attached progress view in a terminal and raw output when redirected; choose raw or attached to override it.

If the agent offers terminal sign-in and the task does not read standard input, “codeflower task” signs in when needed in an interactive terminal, then continues the task. Batch runs and tasks read from standard input still need sign-in beforehand; use “codeflower interactive” once and sign in there. The run is a session of the project, so VS Code lists it afterwards and can continue it.

Exit status: 0 done, 2 not done (the agent judged it impossible, it ran out of rounds or time, or the report failed its check), 3 not signed in, 130 interrupted or timed out, 1 other errors.

Usage

codeflower task (TASK | --prompt FILE) | task --continue TASK_DIR [FOLLOW_UP | --prompt FILE] [flags]

Examples

  codeflower task --agent claude --input ~/data/study42 --output ~/results/study42 \
    "Cluster the cells and annotate the cell types"
  codeflower task --agent claude --model opus --effort high --input ~/data/study42 --output ~/results/study42 \
    "Find the genes that respond to the stimulation in each cell type"
  codeflower task --agent codex --project study42 --input /data/study42 --output ~/results/qc --skip-report \
    "Run quality control and write the filtered matrix"
  sbatch --time=8:00:00 --wrap "codeflower task --agent claude --project study42 \
    --input /data/study42 --output ~/results/study42 --timeout 7h30m --prompt task.md"
  codeflower task --continue ~/codeflower/projects/study42/tasks/1a2b3c --timeout 7h30m
  codeflower task --continue ~/codeflower/projects/study42/tasks/1a2b3c "Also compare the two donors"

Flags

Flag	Default	Description
--agent string		agent the sandbox runs: claude, codex, dsh, or opencode (or set $CODEFLOWER_AGENT; asked if left out)
--allowlist string		file of hosts an isolated sandbox may reach, one per line (default: PROJECT.allowed-hosts.txt next to the project)
--bind stringArray		more mounts: SOURCE[:TARGET[:ro|rw]] (repeatable; default target /data/input/NAME, read-only)
-c, --code stringArray		repository or package the agent develops, mounted read-write at /data/code/NAME (repeatable)
--config string		config directory with config.yaml and skills (or set $CODEFLOWER_CONFIG; default ~/.codeflower)
--continue string		continue the task in this folder (PROJECT/tasks/ID, printed when it started) in its session
--cpus int		CPUs the agent may use (default: the batch job’s allocation; Docker and Podman also enforce it)
--effort string		how hard the model thinks, e.g. low, medium, high or max (default: the agent’s)
--engine string	auto	container engine: auto, docker, podman, or apptainer (or set $CODEFLOWER_ENGINE)
--image string		sandbox image: a Docker/Podman image name, or an Apptainer .sif file (or set $CODEFLOWER_IMAGE; default ghcr.io/lutrarutra/codeflower-sandbox:0.15.1, downloaded on first use)
--image-tag string		build of the published image to use instead of 0.15.1, the release this app is made for: latest, another release (0.2.1, or 0.2 for its newest patch) or a commit (sha-abc1234) (or set $CODEFLOWER_IMAGE_TAG)
-i, --input stringArray		folder with your data, mounted read-only at /data/input/NAME (repeatable)
--isolate-network		cut the sandbox off the network except for its agent’s service and the hosts in the allowlist (Linux)
--max-rounds int	3	how often the agent is sent back to work when it has not finished (a continued task: the same as before)
--memory string		memory the agent may use, e.g. 32G (default: the batch job’s allocation; Docker and Podman also enforce it)
--model string		the agent’s model, e.g. opus, sonnet or claude-opus-5 (default: the agent’s)
--option stringArray		another setting of the agent, ID=VALUE, e.g. fast=on (repeatable)
-o, --output stringArray		folder for results, created if needed and mounted read-write at /data/output/NAME (repeatable)
--output-mode string	auto	task output: auto (attached in a terminal, raw when redirected), raw, or attached
-p, --project string	default	project name: its sessions, logins and workspace live in ~/codeflower/projects/NAME
--prompt string		read the task (with –continue: the follow-up) from this Markdown file instead of an argument
-s, --skills stringArray		folder with a skill (a SKILL.md) or with skill folders, mounted read-only at /data/skills/NAME (repeatable)
--skip-report		do not ask for a storyteller report
--state string		project directory, instead of –project (created with owner-only permissions)
--time-limit string		time the agent has, e.g. 8h or 1-12:00:00 (default: the batch job’s time limit); reported, not enforced
--timeout duration		stop the task after this long, e.g. 90m or 7h30m (default: no limit)