Worktrees give each Code task its own checkout of your repository, so several tasks can edit in parallel without colliding. They are a feature of the desktop app and run on the computer that holds the project; the web app and cloud tasks use sandboxes instead (see Cloud environments). The iOS app does not run anything locally, but its Remote screen can follow Code tasks on a paired desktop (Remote).
What's a worktree
A worktree is an extra checkout of a Git repository with its own files and the shared .git metadata (Git docs). It needs a Git project, and it lets different branches be worked on at the same time.
Terminology
- Local checkout (Local): the original project folder.
- Worktree (New local worktree): a linked checkout ZeroTwo creates from it.
- Move task to worktree and Move task to local checkout: relocate a task between the two.
Why use a worktree
Run an agent in parallel without disturbing the files you are editing, let background work proceed while you focus elsewhere, and move a task into your local checkout when you want to inspect or test it there.
Getting started
-
Turn on Worktree
In the Code setup row above the composer, tick Worktree, or pick New local worktree from the environment pill. A project on this computer must be selected first.
-
Send your prompt
ZeroTwo creates the worktree on a detached HEAD, based on the project's default branch (the remote's default, or
mainormaster). Uncommitted changes in your folder are not copied. If a local environment defines a setup script, it runs at this point. -
Decide where to continue
Stay in the worktree, or move the task to your local checkout from the environment pill's menu.
Working between Local and Worktree
Treat Local as the foreground and the worktree as the background. Git lets a branch be checked out in just one place, so a branch held by a worktree is unavailable in Local, and vice versa. Either keep working in the worktree, or move the task across when you need your usual editor or a single running app.
Option 1: Working on the worktree
A detached worktree has no branch, and pushing is refused until it has one. Use the branch pill's Create and checkout new branch… entry, then commit and push from the commit and push dialog, which offers Commit, Commit and push and Push. The branch then cannot be checked out in any other worktree.
Option 2: Moving a task to Local
Open the environment pill's menu and choose Move task to local checkout to review the changes in your own editor or run your dev server. Move task to worktree does the opposite. The move runs as an operation that keeps the source data if it fails and then offers Retry transfer. When it succeeds, a Task moved note appears.
Advanced details
Where ZeroTwo keeps worktrees
Managed worktrees go under ~/.zerotwo/managed-worktrees by default. Set Worktree root in Settings > Worktrees to use another absolute directory; leaving it blank restores the default. ZeroTwo records which task owns each checkout.
Permanent worktrees
For a long-lived checkout, open a project's menu in the sidebar and choose Create permanent worktree. After you name it, ZeroTwo adds a worktree from the project's current HEAD under ~/.zerotwo/worktrees and lists it as its own project, and it stays until you remove it. Automatic cleanup never touches these.
Setup and cleanup scripts
When a worktree is created, ZeroTwo reads .zerotwo/environments/environment.toml from the source project. Its setup script runs inside the new worktree, and a cleanup script, if present, runs when it is removed. A failed setup keeps the checkout and shows the error with a retry. See Local environments.
Branch limitations
Checking out a branch that another worktree holds fails with Git's own message that the branch is already used by a worktree. Move the task to Local instead, or switch the worktree to another branch. ZeroTwo does not copy ignored files such as .env into a new worktree, so have a setup script create or copy them.
Browsing worktrees
Browse worktrees in the environment pill, the /worktree command and Settings > Worktrees open the same browser. It searches by directory, branch or task, resumes or restores a task, copies a working directory, and deletes a worktree. Deleting keeps the task history and a restorable snapshot, and active, shared, aliased or dirty worktrees cannot be deleted. The /fork command can also fork a chat into a new worktree.
Worktree cleanup
Worktrees use disk space, so Automatically delete old worktrees keeps only the newest ones, with the count set in Auto-delete limit (15 by default). ZeroTwo snapshots a worktree before deleting it, so a pruned one can be restored. Turning automatic deletion off asks for confirmation, since old checkouts then stay on disk until you remove them.
Frequently asked questions
Can I control where worktrees are created?
Yes, through Worktree root in Settings > Worktrees.
Can a task switch between Local and Worktree?
Yes, with Move task to worktree and Move task to local checkout on desktop.
What if a task's worktree gets deleted?
The task stays in your history, and its snapshot can be restored from the worktree browser.