Worktrees¶

A Task can move into a Git worktree of its own, so that its changes stay apart from your main checkout and from other Tasks. Nothing moves automatically; you ask the agent when separation is useful, and the same Task and conversation continue in the worktree.

Move a Task into a worktree¶

Ask the agent in the Task, for example:

Prepare this task in an isolated worktree. Leave my current checkout changes in place. Stop when the worktree is ready.

The agent prepares the worktree with a tool Caffold gives it, and the turn ends there. If the Task's terminal was open, it closes, and the next one starts in the worktree. Your next prompt runs in the worktree:

Now review PR #123.

New Task shows these two prompts as a guide. You can send the first one as the first prompt of a new Task, or later in an existing one.

In the Task list, a branch icon marks a Task that runs in a worktree Caffold prepared. Caffold keeps these worktrees under worktrees/ in its data folder.

Bring your uncommitted changes¶

By default, staged, unstaged, and untracked changes stay in your checkout. To take them along, say so:

Move this task and my current changes into an isolated worktree.

Ignored files and build output stay where they are. An unfinished merge or rebase, or changes inside a submodule, stop the move instead.

Which branch the worktree uses¶

• If the checkout is on a branch other than the default one and has no changes, that branch moves to the worktree, and the checkout switches to the default branch.
• If the checkout is on the default branch or on a detached commit, the worktree gets a new branch named caffold/<task-name>-<id>, unless you ask for a name.
• A branch with uncommitted changes can move only together with those changes, because Git cannot check out one branch in two places. Ask to bring the changes, or commit them first.

Continue with another agent¶

Continuing with another agent starts a new Task, run by that agent, on the same files. The new Task reads the previous one's history and the current files, summarizes where the work stands, and waits for your next request; the previous agent is not asked for a summary.

1. Open the model picker beside the follow-up prompt and select another agent, such as Claude.
2. Choose Continue with Claude, review the model and its options in the dialog, and continue.

A worktree Caffold prepared moves to the new Task with its uncommitted changes and build output, and the previous Task stays in Active so you can read its conversation; its notice links to the new Task. In an ordinary directory or a worktree Caffold did not prepare, both Tasks remain usable.

Creating the Task and receiving its summary are separate steps. If creation succeeds but opening fails, use Open created Task. If the connection ends without a result, check the Task list before trying again.

Clean up¶

Archiving a Task removes the worktree Caffold prepared for it and keeps its branch; see Archive, restore, and delete. Caffold never removes a worktree it did not prepare, and never deletes a branch.

If removal fails and leaves the worktree unusable, its Task can show Delete task instead of Retry. See Delete a broken worktree Task for the permanent deletion dialog and what it removes.