Git worktrees
Create independent checkouts for parallel tasks, then merge, publish, or remove them when the work is done.
A Git worktree gives a task a separate working directory in the same repository. Dream opens it as another project, with its own chats and tools. Use worktrees when agents need to edit independently without changing each other's checkout.
Create a worktree#
Start from a project that is a Git repository with a committed base ref.
- Open the branch switcher beneath the chat.
- Choose New worktree.
- Enter a name for the new Branch, such as
fix-settings-persistence. - Set Base ref to the commit or branch you want to start from, such as
main. - Click Create worktree.
Dream creates the checkout and opens its project. Check the worktree branch shown beneath the chat before sending the task. Commands and agent edits in this project use the new directory.
The base ref must exist in your local repository. If you need newer remote commits, fetch them through your normal Git workflow before creating the worktree.
Carry a conversation into a worktree#
From a message, choose Continue from this message… → New worktree. Dream copies the conversation through that message, uses the current branch as the base, and generates a new branch name.
Use this shortcut when you want the agent to continue with the earlier discussion. Use the branch switcher workflow when you need to choose a custom base and branch name. See Branching conversations for the difference between copying messages and copying files.
Worktrees start from committed Git history. Uncommitted changes in the original project are not copied. A chat branched from an earlier message does not recreate the filesystem at that point in the conversation.
Move between checkouts#
Use the project tabs to switch between the original checkout and the worktree project. App-managed worktrees also appear in the parent project's Chat history panel, where you can open them again.
Review and commit changes from the project where they were made. Creating a worktree does not merge its changes into the original branch; use the footer's Git actions when the work is ready.
Complete a worktree#
Merging, creating a pull request, and removing a worktree are separate actions in the footer's Git actions menu. Commit the changes you want to include before merging.
- In the worktree project, choose Merge into base from Git actions beneath the chat.
- Review the summary: the Base branch, how many Commits the branch is ahead and behind, the changed Files, and the Main checkout's current branch and whether it is clean.
- Read the commit list and expand any file to inspect its diff.
- Use Commit changes... if needed. Uncommitted changes stay in the worktree and are not merged.
- Choose Merge into base. Dream merges committed work in the main checkout, switching it to the base branch if needed.
- Review the result, then choose Keep worktree or Remove worktree and branch. Removal after merging is offered only when the worktree is clean.
To publish for review instead, use Git actions → Create pull request and follow Git workflows. Creating a PR keeps the worktree.
Use Git actions → Remove worktree to remove the checkout while keeping its branch. If it has uncommitted changes, commit them first or explicitly select Discard uncommitted changes.
Removing a worktree deletes its directory and closes its project. The worktree project's chats are discarded with it and do not appear in Chat history or Recently closed. If you want to keep a conversation, branch it into the parent workspace before completing.
When an option is unavailable#
| Message | What to do |
|---|---|
| This branch has no commits ahead of base | Commit the work you want to keep, or choose Remove worktree |
| The main checkout has uncommitted files | Commit or stash changes in the parent project before merging |
| The main checkout has a merge or rebase in progress | Finish or abort that operation in the parent project |
| This branch shares no history with base | Merge through your own Git workflow |
| No Git remote is configured | Add a remote before creating a pull request |
| GitHub CLI (gh) is not available | Install and authenticate GitHub CLI |
If the merge produces conflicts, Dream aborts it and reports Merging into base produced conflicts. The merge was aborted and nothing was changed, with the conflicting files. Bring the base branch into the worktree, resolve the conflicts, commit, and then run Merge into base again.
Remove a worktree from the parent project#
You can also remove a worktree without the completion dialog:
- Preserve the work you need by committing it and, if appropriate, pushing it or opening a PR.
- Stop processes using the worktree, such as a local application running in its terminal.
- Open the parent project's Chat history panel and find the worktree.
- Use its remove action and review the confirmation.
- Confirm Remove worktree when you no longer need that checkout.
Removal deletes the worktree directory from disk. Git refuses removal when it contains uncommitted changes. Return to that project and review the changes before trying again.
Closing a project tab only removes it from the open workspace; removing a worktree deletes its checkout. For commit and PR steps, see Git workflows.