Skip to main content
A worktree is a separate checkout of the same git repository. Traycer uses worktrees so agent work can run in an isolated folder without changing the main workspace folder. Worktree choices are made per workspace folder. A Task can include more than one workspace folder, and each folder can use its own run location.

​
Run Locations

When Traycer asks where a chat or Terminal Agent should run, each workspace folder can use one of these locations:
LocationWhat it doesWhen it is available
LocalRuns against the workspace folder itself.Always available. For non-git folders, this is the only option.
New worktreeCreates a new git worktree for the run.Available for git repositories.
Existing worktreeUses an already-created worktree for that repo.Available when the Host finds existing worktrees for the workspace folder.
For a New worktree, you can choose the branch source. If the current working tree has uncommitted changes, the branch picker can show a Working tree source. Choose that source when you want Traycer to carry those changes into the new worktree. For an Existing worktree, the branch is fixed by that worktree. Traycer uses it as-is.

​
New Worktree Branch Options

When you choose New worktree, the branch picker shows source branches. The source you choose controls whether Traycer creates a new branch, checks out an existing branch, or carries current changes.
SourceWhat happens
Current branchTraycer creates a new branch from the current branch and checks it out in a fresh worktree. This is the default clean path.
Working treeTraycer creates a new branch from the current branch and carries uncommitted changes. This appears when the working tree has changes to carry.
Other local branchIf you leave the new branch name blank, Traycer checks out that branch in a fresh worktree. If you enter a new branch name, Traycer creates a new branch from that source branch.
Remote branchTraycer creates a local branch from the remote source. The branch name is required and is prefilled from the remote branch name.
Branches that are already checked out in another worktree appear under Existing worktree, not as checkout options in the New worktree branch picker.

​
Where You Choose A Worktree

Worktree choices appear in the places where Traycer starts agent work:
PlaceWhat you can choose
New Task / first chatWorkspace folders and the run location for each folder.
Existing chatThe run location for the next agent turn.
New chat in an existing TaskThe starting run location for that new chat.
Terminal Agent launchWorkspace folder, run location, coding agent, model, mode, thinking effort, and terminal-agent arguments. These choices stay fixed after launch.
Git DiffWhich worktree’s changed files to inspect.
In chats, worktree changes apply to the next agent turn. If Traycer needs to create or set up a worktree first, the chat shows setup progress before the agent continues. Terminal Agents are different: their workspace and worktree choices are fixed when the Terminal Agent starts.

​
Worktree Setup

When Traycer creates a worktree, it can run setup and teardown scripts for that workspace folder. The setup controls let you:
  • edit setup and teardown scripts for a folder
  • create a new branch in a fresh worktree
  • check out an existing branch in a fresh worktree
  • create a worktree from the Working tree source when uncommitted changes should be carried over
  • use an existing worktree instead of creating a new one
Setup can show states such as Creating worktree, Setting up worktree, Worktree ready, Setup failed, or Setup cancelled. Troubleshooting those states is covered in Troubleshooting.

​
Existing Worktrees

Existing worktrees are useful when you already have a checkout for a branch and want Traycer to use that folder instead of creating another one. When you select an existing worktree:
  • Traycer runs in that existing checkout
  • the branch is read-only in the picker because it belongs to the selected worktree
  • the worktree can appear in Git Diff and file-related views for that Task

​
Managing Worktrees

Settings > Worktrees is for management: reviewing worktrees on a Host, refreshing the list, and deleting worktrees when they are safe to remove. The CLI can also create worktree paths without creating an agent. See CLI.