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 Complete worktree when the work is ready.
Complete a worktree#
The Complete worktree dialog reviews the worktree branch against its base, then merges it, opens a pull request, or simply removes the checkout.
- In the worktree project, click the worktree button showing the branch name beneath the chat. Its tooltip is Complete worktree followed by the branch.
- 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.
- If the dialog lists uncommitted files, click Commit changes... to commit them, or select Discard uncommitted changes to let them be deleted with the worktree.
- Under Next steps, choose one option.
- Click Merge & remove, Continue to pull request, or Remove worktree.
| Next step | What happens |
|---|---|
| Merge into base and remove worktree | Merges the branch into the base from the main checkout, removes the worktree, and deletes the branch |
| Create pull request and remove worktree | Opens the pull-request dialog, then removes the worktree and keeps the branch |
| Remove worktree only | Removes the worktree and keeps the branch |
Dream preselects merge when it is possible, then pull request, then remove. The merge runs
git merge in the main checkout; if that checkout is on another branch, Dream switches it to the
base branch first and tells you so in the summary. A base branch that exists only on the remote is
created locally.
The Done screen reports the result: whether the base was fast-forwarded or received a merge commit, whether the main checkout switched branches, a View pull request button when a PR was created, and whether the branch was deleted or kept.
Completing 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 only |
| 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 |
The primary button stays disabled while the worktree has uncommitted changes and you have neither committed nor chosen to discard them. The pull-request path lets you commit inside the PR dialog.
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 Complete worktree 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.