> ## Documentation Index > Fetch the complete documentation index at: https://docs.traycer.ai/llms.txt > Use this file to discover all available pages before exploring further. # Worktrees > Understand how Traycer uses workspace folders and git worktrees for chats, terminal agents, and diffs. 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: | Location | What it does | When it is available | | --------------------- | ----------------------------------------------- | -------------------------------------------------------------------------- | | **Local** | Runs against the workspace folder itself. | Always available. For non-git folders, this is the only option. | | **New worktree** | Creates a new git worktree for the run. | Available for git repositories. | | **Existing worktree** | Uses 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. | Source | What happens | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Current branch** | Traycer creates a new branch from the current branch and checks it out in a fresh worktree. This is the default clean path. | | **Working tree** | Traycer creates a new branch from the current branch and carries uncommitted changes. This appears when the working tree has changes to carry. | | **Other local branch** | If 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 branch** | Traycer 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: | Place | What you can choose | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | **New Task / first chat** | Workspace folders and the run location for each folder. | | **Existing chat** | The run location for the next agent turn. | | **New chat in an existing Task** | The starting run location for that new chat. | | **Terminal Agent launch** | Workspace folder, run location, coding agent, model, mode, thinking effort, and terminal-agent arguments. These choices stay fixed after launch. | | **Git Diff** | Which 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](/reference/troubleshooting#worktree-setup). ## 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](/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](/cli/commands#workspace-and-worktree-commands).