Start a Task¶
A Task is one piece of work given to one agent. You start it with a directory, a model, and a first prompt.
Start from New Task¶
- Choose New Task (+) at the top of the Task list.
- Check the directory above the prompt; the Task works there. To change it, select the directory and choose a folder from the list, or choose the pencil button, type or paste a path, and press Enter.
- Open the model menu, which shows the current model. Under Provider, choose the agent, then choose one of its models under Model. When the model offers them, the same menu also sets the Reasoning level and Speed.
- Choose an approval mode from the button beside it. See Approvals.
- Write the prompt and send it. You can attach files to it, or dictate it.
The Task opens right away and your prompt appears immediately in the
conversation. Near the end of the first turn,
the agent names the Task after what you asked for. To rename it later, ask the
agent, for example Rename this task to Dark theme.
Attach files¶
Every Composer takes files: New Task, a Task's next prompt, and a prompt you send into a running turn. Attach up to ten files of up to 5 GB each:
- choose Attach files, the paper clip, and pick them;
- paste files or screenshots into the prompt; or
- drop them on the Composer.
Folders cannot be attached. A picture shows as a thumbnail you can choose to see larger, and any other file by its name; the X on each takes it out.
Sending uploads the files to the host one at a time, into a folder of their own
under .caffold/uploads/ in the Task's working directory, and upload progress
appears in the message. Cancel upload stops it and returns the prompt
to the Composer; during a running turn, that button is Stop current turn and
also stops the turn.
Once the files are up, the prompt reaches the agent with an Attached files list of their paths, which the agent reads and the conversation shows.
A PNG, JPEG, GIF, WebP, or AVIF picture of up to 10 MB also reaches the agent as an image; whether the agent reads it depends on the model you chose. Any other file reaches the agent through its path.
Files the agent received stay in the working directory. Caffold keeps them out of Git, so they do not show in Working Tree, and archiving a Task in a Caffold worktree removes them with the worktree.
The model chooses the agent¶
Every model belongs to one agent: Codex, Claude Code, Grok, or Antigravity. The model you choose for a new Task decides which agent runs it, and the Task keeps that agent for its whole life. To continue the same files with another agent, open the model picker, choose that agent, then its Continue with button; see Worktrees.
Between turns you can still change the model, among the same agent's models, and the reasoning level and speed the model offers. Whether the approval mode can change depends on the agent; see Approval modes.
Other ways to start a Task¶
- From a Section. Select a Section in the Task list to start a Task in its directory with the choices last used there. See Sections.
- From GitHub. An Issue or a Pull Request can start a Task that prepares its own worktree. See GitHub.
- From an existing conversation. Fork a Codex, Claude Code, or Grok conversation into a new Task. See Fork a conversation.