Run Locations
When Traycer asks where an agent should run, each workspace folder can use one of these locations:
For a New worktree, you choose the source the new branch starts from and the new branch’s name. In the app, a new worktree always gets a new branch.
For an Existing worktree, the branch is whatever that worktree has checked out. Traycer uses it as-is.
New Worktree Branch Options
When you choose New worktree, click the folder’s branch control to open the form. It has a Source list, with a Search branches box, and a New branch name field. The name is required (“New branch name (required)”), and the form saves on its own: its status reads Saving…, then Saved.
The list shows every local branch except the one checked out in the folder, including branches checked out in other worktrees, most recently committed first. A remote branch is listed only when there is no local branch with the same name.
Generated names use your branch prefix, for example
traycer/swift-otter. If you keep a generated name and a branch with that name already exists, Traycer picks another generated name. If you typed the name yourself and the branch exists, creating the worktree fails.
To check out an existing branch into a fresh worktree without creating a new branch, use the CLI:
traycer worktree create --existing <branch>. See CLI.Where You Choose A Worktree
Worktree choices appear in the places where Traycer starts agent work:
On the Chat interface, worktree changes apply to the next agent turn. If Traycer needs to create or set up a worktree first, the agent shows setup progress before continuing. The Terminal interface is different: an agent’s workspace and worktree choices are fixed when it starts.
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. Pick Existing worktree in the folder’s run location menu, then choose a worktree from the list. Each entry shows its branch, its path, and how many uncommitted changes it has. With more than five worktrees, a Search worktrees box appears. 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
Setup and Teardown
A repository can run a setup script in each new worktree, for example to install dependencies, and a teardown script before a worktree is removed. You edit both, and the repository’s branch prefix, with the gear Repository settings button on the folder’s row in the workspace picker. They are stored in the repository’s.traycer/environment.json.
While Traycer creates and sets up a worktree, the agent shows a setup card: Creating worktree, Setting up worktree, then Worktree ready. If something goes wrong, the card shows Setup failed, Setup cancelled, or Worktree creation failed, with Open terminal and Retry setup or Retry creation.
See Setup and Teardown Scripts for the file format, how setup and teardown run, and every setup state. For fixing setup problems, see Troubleshooting.
Where Worktrees Live
Traycer creates worktrees on the host, under your home folder:<owner> and <repo> come from the repository’s remote, and <slug> comes from the branch name. A repository without a recognized remote uses a local__<folder>__<id> folder instead of <owner>__<repo>.
Only worktrees in this folder appear in Settings › Worktrees, and only these can be removed by Traycer.