> ## Documentation Index
> Fetch the complete documentation index at: https://wonder.design/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Worktrees and parallel agents

> Give each chat its own copy of your repository on its own branch, so several agents work at once. Create worktrees from a branch or pull request, copy .env files, run a setup command, add design files, and archive and restore them.

A worktree is a separate copy of your project, on its own branch and in its own folder. Each chat in a repository works in its own worktree, so several agents can work at once without changing each other's files.

**Before you start** · Desktop app · Free plan

You need a repository in Wonder. See [Add a repository](https://wonder.design/docs/add-a-repository.md).

## How worktrees work

* **Every new chat in a repository gets a new worktree**, with a new branch, from your repository's base branch.
* **It gets its name from the chat.** A new worktree starts with a placeholder name. Once your first message gives the chat a title, the worktree and its branch take that title. Branch names start with your **Branch prefix** (**Settings > Agents > Projects and worktrees**), or your GitHub username if you haven't set one.
* **Its folder is in your Wonder folder**, `~/wonder/workspaces/`, in a folder named after the repository. See [Where Wonder keeps your code](https://wonder.design/docs/add-a-repository.md#where-wonder-keeps-your-code).
* **The worktree holds everything for that piece of work**: its chats, terminals, Preview, design files and pull request.

The sidebar lists each repository's worktrees under it in **Repositories**. A worktree's icon shows what its agent is doing, such as **Agent working**, **Agent needs approval**, **Agent has a question** or **Agent finished responding**. To see lines added and removed next to each worktree, turn on **Line changes in sidebar** in **Settings > Preferences > Advanced**.

## Create a worktree

1. In the sidebar, click **+** (**New worktree**) on the repository's row. You can also open the repository's menu (**⋯**) and choose **New worktree**.
2. Type your first message and send it.

A worktree starts from the branch set in **Start new worktrees from** in the repository's **Repository settings > Worktrees**. By default, that's your repository's default branch on GitHub, fetched fresh, or the current branch of the repository's folder when it has no remote.

You can also click **Create new chat** in the sidebar, or choose **New chat** in <kbd>⌘</kbd> <kbd>K</kbd>. On the new chat screen, the **Start in** menu picks where the chat goes: a **New worktree in** one of your repositories, or a **Quick chat** with no repository.

To keep several chats in the same worktree instead, see [Open chats as tabs](https://wonder.design/docs/manage-your-chats.md#open-chats-as-tabs).

### Run several agents at once

Start another worktree while an agent is still working in the first one. Each agent works in its own folder and on its own branch, so you can have one fixing a bug while another builds a feature, and open a pull request from each.

To keep the worktrees you're using at the top, open a worktree's menu and choose **Pin**. Drag worktrees to reorder them, or select one and press <kbd>⌥</kbd> <kbd>↑</kbd> or <kbd>⌥</kbd> <kbd>↓</kbd>.

## Create a worktree from a branch or pull request

1. Open the repository's menu (**⋯**) in the sidebar and choose **Create from**.
2. Choose **Pull Requests** or **Branches**, and type to search. **Pull Requests** lists open pull requests; type a number, such as `#42`, to find a merged or closed one.
3. Click the pull request or branch.

![The Create from dialog on its Branches tab, with a Search for branch field above a list of the repository's branches](https://mintcdn.com/wonder-0722b0f6/Ig4tBDjfjeU3SKs6/images/work-with-your-code/create-from.light.webp?fit=max\&auto=format\&n=Ig4tBDjfjeU3SKs6\&q=85\&s=04386ea57cad934716f8f841caf588a0)

![The Create from dialog on its Branches tab, with a Search for branch field above a list of the repository's branches](https://mintcdn.com/wonder-0722b0f6/Ig4tBDjfjeU3SKs6/images/work-with-your-code/create-from.dark.webp?fit=max\&auto=format\&n=Ig4tBDjfjeU3SKs6\&q=85\&s=fdfded08597d7f3c31b8065a90b307b6)

The worktree checks out that branch and is named after it, or after the pull request's title. A merged or closed pull request can be checked out only while its branch is still on GitHub; otherwise Wonder says **That branch no longer exists on its remote**.

A pull request from someone else's fork shows **From a fork**. Wonder doesn't trust code from a fork: it doesn't run your worktree setup command there, won't open its files in apps that could run them, and a chat that works on it runs contained. See [Chats that worked on a fork's pull request](https://wonder.design/docs/permission-modes-and-approvals.md#chats-that-worked-on-a-fork’s-pull-request).

## Copy .env and other ignored files

A worktree is a fresh copy of your repository from Git, so it doesn't have the files Git ignores, such as `.env`. List the ones your app needs, and Wonder copies them into each new worktree:

1. Open the repository's menu (**⋯**) in the sidebar and choose **Repository settings**, then **Worktrees**.
2. Under **Files to copy**, add one path or glob per line, for example `.env`, `**/.env.local` for a file at any depth, or `certs/**` for a folder. Or click **Choose files…** to pick them.

Repository settings save as you type.

Wonder copies these from your repository's own folder. A file you pick from elsewhere with **Choose files…** is copied to the root of each new worktree. Only files Git ignores can be copied, up to 200 files, 5 MB each and 20 MB in total. Symbolic links, folders and names with characters such as `(`, `)` or `~` can't be copied.

Under an entry Wonder can't copy, such as a file Git doesn't ignore, the settings say why, with **Locate…** and **Remove**. New worktrees aren't created until you fix or remove that entry. An entry that matches nothing doesn't stop them: new worktrees are created without it.

If you start the Preview in a worktree that's missing a secret file, Wonder offers to copy it and adds it to **Files to copy** for you. See [Your app needs a secret file](https://wonder.design/docs/fix-preview-problems.md#your-app-needs-a-secret-file).

## Run a setup command in each new worktree

The **Worktree setup command** runs once in each new worktree, after Wonder copies your files and before its chat starts. Use it to link or copy local config or fix paths, for example with a script you commit to the repository.

1. Open **Repository settings > Worktrees**.
2. Under **Worktree setup command**, type the command, such as `./scripts/setup-worktree.sh`. Chain steps with `&&`. It saves as you type.

While it runs, the worktree says **Setting up…** and the chat says **Running the worktree setup command…**. You can type your first message meanwhile; it's sent once setup finishes. The command can run for up to 10 minutes.

The command runs in the worktree's folder and gets these environment variables, along with the values in your repository folder's `.env`:

| Variable | Value |
| - | - |
| `WONDER_PROJECT_PATH` | Your repository's own folder |
| `WONDER_WORKTREE_PATH` | The new worktree's folder |
| `WONDER_WORKTREE_NAME` | The name of the worktree's folder |

Repository settings are saved on this computer, not in the repository, so each person sets their own command.

To run it again in a worktree, open the worktree's menu and choose **Run setup command**. It waits until the agent finishes.

If the command fails, Wonder keeps the worktree and says so. Click **Show output** to see what it printed.

This is different from the Preview's **Setup command**, which installs what your app needs before the Preview starts it. See [Set up the Preview](https://wonder.design/docs/set-up-the-preview.md).

> [!NOTE]
>
> **Moving from Conductor?**\\
>
> If your repository has a Conductor setup or archive script, **Repository settings > Worktrees** offers **Use Conductor's setup script** and **Use Conductor's archive script**. Wonder doesn't run them until you accept. See [Move from Conductor](https://wonder.design/docs/migrate-from-conductor.md).

## Give a worktree its design files

A worktree can hold up to 50 Wonder files. Every chat in the worktree designs in them.

While a worktree has none, its chat says **This worktree has no canvas file attached yet**. Click **Create file** for a new one, or **Add file** to pick one of yours. You can also:

* Type `/add-file` in the chat, or click **+** in the message box and choose **Add file**.
* With a file open, click the suggestion to add it to this worktree. It joins when you send your message.

**Works with**, at the top of the message box, lists the worktree's files. To take one out, see [Choose what a chat works with](https://wonder.design/docs/choose-what-a-chat-works-with.md).

To give every new worktree the same files, add them under **Canvas files** in **Repository settings > Context**.

## Open a worktree in Finder, a terminal or your editor

Open the worktree's menu in the sidebar:

* **Show in Finder** opens its folder.
* **Open in terminal** opens your terminal app in its folder.

To open a file in your editor, such as Cursor or Visual Studio Code, use **Open in** on the file. See [Open a file in your editor](https://wonder.design/docs/files-changes-and-terminal.md#open-a-file-in-your-editor). For a terminal inside Wonder, use the side panel's terminal.

## Rename a worktree

Double-click the worktree in the sidebar, or open its menu and choose **Rename**. This changes the name Wonder shows, not its branch or folder.

## Archive and restore a worktree

Archive a worktree when you're done with it, for example once its pull request merges:

* Hover the worktree and click **Archive worktree**, or choose **Archive worktree** in its menu.
* After a merge, click **Archive** on the Ship button. See [Merge and archive](https://wonder.design/docs/commit-push-and-pull-requests.md#merge-and-archive).

Archiving stops the worktree's agents and anything running in it, and moves it and its chats to **Archived**. Its folder, its uncommitted changes and its branch stay on your computer. By default, when the Preview has a setup command to reinstall them, Wonder also removes folders Git ignores, such as `node_modules`, to save space; the Preview runs its setup again after you restore the worktree.

To restore one:

1. Click **Archived** in the sidebar's **Repositories** header. It shows when something is archived.
2. Find the worktree under **Worktrees** and click **Restore**.

Sending a message in an archived worktree's chat restores it too.

### Choose what happens when you archive

In **Repository settings > Worktrees**, under **Archiving**:

| Setting | What it does | Default |
| - | - | - |
| **Archive when its pull request merges** | Archives the worktree when its pull request merges, if nothing is uncommitted and no agent is working. A notice gives you a few seconds to click **Unarchive**. | Off |
| **Archive command** | Runs as the worktree is archived, for example to stop services. It can run for up to 60 seconds. | None |
| **Delete the local branch on archive** | Deletes the branch for a worktree with nothing uncommitted. GitHub keeps its branch, and restoring brings it back. | Off |
| **Remove dependency folders on archive** | Deletes folders Git ignores, such as `node_modules`, unless the Preview has no setup command to reinstall them. | On |
| **Delete archived worktrees after** | Deletes archived worktrees from your computer after 7, 14, 30, 60 or 90 days. Ones with uncommitted changes or unpushed commits are kept. | On, 30 days |

### Delete archived worktrees

In **Archived**, click the delete button on a worktree, or **Delete all worktrees**. Deleting removes its folder from your computer, and any uncommitted changes in it. Its branch and commits stay in the repository. When your disk is almost full, the sidebar shows **Free up space**, which deletes your archived worktrees.

## Work in the repository folder instead

You can let a chat work in your repository's own folder, on whatever branch it's on, without a worktree. Its changes land directly in that folder, so don't run two agents there at once.

1. Turn on **Show advanced repository controls** in **Settings > Agents > Projects and worktrees**.
2. Open the repository's menu (**⋯**) and choose **Work in the repository folder**.

To make this the default for a repository, set **Where new chats work** to **The repository folder** in its **Repository settings > Worktrees**.

A folder you added without Git always works this way, since it can't have worktrees.

## If something goes wrong

* **"This branch is already checked out in the repository or another worktree".** Open that checkout instead, or click **Create anyway** to work on a copy of the branch in a new worktree.
* **"Wonder can't tell which branch new worktrees should start from".** Click **Choose base branch** and pick one in **Start new worktrees from**.
* **"Couldn't fetch the latest base branch".** Check your connection. If Wonder goes ahead anyway, it says the worktree starts from the base branch as this computer last fetched it.
* **"The files to copy exceed 5 MB per file, or 20 MB or 200 files in total".** Copy fewer or smaller files in **Files to copy**.
* **"The worktree setup command failed".** Click **Show output** to see why. The worktree is still there; fix the command and choose **Run setup command**.
* **"The worktree setup command didn't run, since this worktree or the files copied into it come from a place Wonder doesn't trust".** The worktree holds a fork's pull request. Check its code before you run anything from it.
* **"This worktree has as many files as it can hold".** Remove a Wonder file from **Works with** to make room.
* **"Another worktree has this worktree's branch checked out now".** Switch that worktree to another branch, then restore this one.
* **"Your disk is full".** Click **Free up space** in the sidebar, or delete archived worktrees in **Archived**.

## Related

* [Add a repository](https://wonder.design/docs/add-a-repository.md)
* [Choose what a chat works with](https://wonder.design/docs/choose-what-a-chat-works-with.md)
* [Commit, push and pull requests](https://wonder.design/docs/commit-push-and-pull-requests.md)
* [Set up the Preview](https://wonder.design/docs/set-up-the-preview.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.