Skip to main content
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.

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.
  • 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 ⌘ K. 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.

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 ⌥ ↑ or ⌥ ↓.

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 branchesThe Create from dialog on its Branches tab, with a Search for branch field above a list of the repository's branches
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.

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.

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: 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.
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.

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. 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. 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.
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:

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.