> ## 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 agents and diffs.

export const FeatureVideo = ({src, label}) => {
  const videoRef = React.useRef(null);
  React.useEffect(() => {
    const video = videoRef.current;
    if (!video || typeof IntersectionObserver === "undefined") {
      return undefined;
    }
    const reduceMotion = typeof window !== "undefined" && typeof window.matchMedia === "function" && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
    if (reduceMotion) {
      return undefined;
    }
    let pausingOffScreen = false;
    let pausedByReader = false;
    const onPause = () => {
      if (pausingOffScreen) {
        pausingOffScreen = false;
        return;
      }
      pausedByReader = true;
    };
    const onPlay = () => {
      pausedByReader = false;
    };
    video.addEventListener("pause", onPause);
    video.addEventListener("play", onPlay);
    const observer = new IntersectionObserver(entries => {
      for (const entry of entries) {
        if (entry.isIntersecting) {
          if (!pausedByReader) {
            video.play().catch(() => {});
          }
        } else if (!video.paused) {
          pausingOffScreen = true;
          video.pause();
        }
      }
    }, {
      threshold: 0.25
    });
    observer.observe(video);
    return () => {
      observer.disconnect();
      video.removeEventListener("pause", onPause);
      video.removeEventListener("play", onPlay);
    };
  }, []);
  return <video ref={videoRef} className="w-full aspect-video rounded-xl" controls loop muted playsInline preload="metadata" aria-label={label}>
      <source src={src} type="video/mp4" />
      Unable to load video.
    </video>;
};

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 an 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 a folder that isn't a git repository, this is the only option ("Worktrees require a Git repository. This folder can only run Local."). |
| **New worktree** | Creates a new git worktree on a new branch for the run. | Available for git repositories. |
| **Existing worktree** | Uses another worktree of the same repository that already exists on disk. | Listed when the repository has other worktrees. Otherwise the menu shows "No existing worktrees". |

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.

<FeatureVideo src="https://assets.traycer.ai/docs/videos/worktree-run-location.mp4" label="Choose a new worktree and branch" />

## 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**.

| Source | What happens |
| - | - |
| **Working tree** | Listed as "Working tree · " followed by the current branch. Creates the new branch from the current branch and carries your uncommitted changes, tracked and untracked, into the new worktree. Shown only when the folder has uncommitted changes, with an "N uncommitted" badge. |
| Current branch | Creates the new branch from the branch checked out in the folder, without your uncommitted changes. This is the default. |
| Another local branch | Creates the new branch from that branch. The name is prefilled with a generated name. |
| Remote branch (marked "remote") | Creates a local branch from the remote branch. The name is prefilled with the remote branch's name, without the remote. |

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](/concepts/worktrees/scripts#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.

<Note>
  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](/cli/commands).
</Note>

## Where You Choose A Worktree

Worktree choices appear in the places where Traycer starts agent work:

| Place | What you can choose |
| - | - |
| **New Task / first agent** | Workspace folders and the run location for each folder. |
| **Existing agent** | The run location for the next agent turn. |
| **New agent in an existing Task** | The starting run location for that new agent. |
| **Terminal interface launch** | The workspace folder and run location, among the other launch choices. They stay fixed after launch; see [Terminal Agents vs Terminals](/concepts/terminal-agents-vs-terminals). |
| **Git Diff** | Which worktree's changed files to inspect. |

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](/concepts/worktrees/scripts) for the file format, how setup and teardown run, and every setup state. For fixing setup problems, see [Troubleshooting](/reference/troubleshooting).

## Where Worktrees Live

Traycer creates worktrees on the host, under your home folder:

```text theme={null}
~/.traycer/worktrees/<owner>__<repo>/<slug>
```

`<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](/settings/worktrees), and only these can be removed by Traycer.

## Managing Worktrees

[Sweep](/concepts/sweep) cleans up worktrees belonging to one or more Tasks while keeping the Tasks, conversations, and artifacts. Open it from a Task's status row or History to review what will be removed. Sweep preselects idle worktrees whose work is proven safe to remove and shows additional consequences for shared, active, or unverified work.

[Settings › Worktrees](/settings/worktrees) lists every worktree Traycer created on a host, with its status, and lets you delete them or turn on automatic cleanup. Deleting Tasks in [History](/concepts/history#delete-tasks) can remove their worktrees too.

Removing a worktree deletes its folder, including uncommitted and ignored files. It keeps the branch, so committed work stays on that branch. The exception is a submodule checked out on its own branch for that worktree: the submodule's branch lives inside the worktree and is deleted with it, together with any commits that exist only there. When you delete a worktree yourself, Traycer also closes any terminal open inside it.

The CLI can also create, list, and delete worktrees. See [CLI](/cli/commands).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.