Interactive, run and task

Command	Starts	Then
codeflower interactive	a sandbox	you connect and chat
codeflower run TASK	a sandbox and a chat with TASK as its first message	the agent starts at once; you connect to follow and continue
codeflower task TASK	a sandbox that works on TASK by itself, no window	it stops when done, and leaves a report

All three take the same folders and project flags, --agent, --engine, --image and the network flags.

interactive

codeflower interactive --agent codex -p study42 -i ~/data/study42 -o ~/results/study42

Prints the codeflower:// address to paste into VS Code or the app’s window, and keeps running until Ctrl+C.

With --server, the sandbox also serves the chat page itself and prints a link (http://HOST:PORT/?key=…) that opens it in any browser that can reach the machine, e.g. through ssh -L. Anyone with that link controls the agent, and plain HTTP carries it unencrypted: prefer --host 127.0.0.1 with an SSH tunnel on shared networks.

run

codeflower run -p study42 -i ~/data/study42 -o ~/results/study42 \
  "Run quality control on the samples and summarise the problems you find."

TASK can also be - (read from standard input) or --prompt FILE (a Markdown file). The chat appears in the sandbox’s list of sessions, so you can open it while the agent works, answer its questions, and keep going when it is done. If the agent is not signed in yet, the first message waits until you connect and sign in.

task

codeflower task -p study42 -i ~/data/study42 -o ~/results/study42 --timeout 8h \
  --prompt analysis-plan.md

The agent gets the task as its goal and is told that nobody is there to answer questions. It works until it judges the task done, or for at most --max-rounds rounds (default 3). Its results go to the first --output folder, with a report, report.html, that it builds as it goes (--skip-report leaves it out).

Stopping cleanly. Before --timeout runs out (a tenth of it, between 2 and 15 minutes), or when the rounds run out, the agent is told to stop starting new work and write up what it did, found and left open. Press Ctrl+C to ask for the same; press it twice to cancel.

Choosing a model. --model, --effort and --option ID=VALUE choose among what the agent offers, e.g. --model opus --effort high for Claude Code. Defaults can go in config.yaml under agents.<id>.

Continuing. The task’s folder (PROJECT/tasks/ID) is printed when it starts. codeflower task --continue TASK_DIR runs it again in the same chat: after an interruption or a failure the agent picks up where it stopped. Add a follow-up to ask for more:

codeflower task --continue ~/codeflower/projects/study42/tasks/ab12cd "Also compare donors 3 and 4."

A continued task keeps its project, agent, folders, network and report settings.

Exit status, for scripts and batch jobs:

Code	Meaning
0	done
2	not done: the agent judged it impossible, it ran out of rounds or time, or the report failed its check
3	the agent is not signed in
130	interrupted or timed out
1	any other error

Sign in first

A batch job cannot answer a sign-in. Run codeflower interactive -p PROJECT once, sign in, and every task of that project is signed in. In an interactive terminal, task can sign in by itself when needed.

The finished task is a chat of the project: open it later in VS Code or the app to ask about the results.