Dream
DocumentationDownload
Git

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.

  1. Open the branch switcher beneath the chat.
  2. Choose New worktree.
  3. Enter a name for the new Branch, such as fix-settings-persistence.
  4. Set Base ref to the commit or branch you want to start from, such as main.
  5. Click Create worktree.
Choose New worktree at the bottom of the branch switcher to create an independent checkout.

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.

Complete a worktree
  1. In the worktree project, choose Merge into base from Git actions beneath the chat.
  2. 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.
  3. Read the commit list and expand any file to inspect its diff.
  4. Use Commit changes... if needed. Uncommitted changes stay in the worktree and are not merged.
  5. Choose Merge into base. Dream merges committed work in the main checkout, switching it to the base branch if needed.
  6. Review the result, then choose Keep worktree or Remove worktree and branch. Removal after merging is offered only when the worktree is clean.
Review changes
Complete a worktree

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#

MessageWhat to do
This branch has no commits ahead of baseCommit the work you want to keep, or choose Remove worktree
The main checkout has uncommitted filesCommit or stash changes in the parent project before merging
The main checkout has a merge or rebase in progressFinish or abort that operation in the parent project
This branch shares no history with baseMerge through your own Git workflow
No Git remote is configuredAdd a remote before creating a pull request
GitHub CLI (gh) is not availableInstall 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:

  1. Preserve the work you need by committing it and, if appropriate, pushing it or opening a PR.
  2. Stop processes using the worktree, such as a local application running in its terminal.
  3. Open the parent project's Chat history panel and find the worktree.
  4. Use its remove action and review the confirmation.
  5. 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.