> ## Documentation Index
> Fetch the complete documentation index at: https://mux-mike-fix-3722-code-workspace-sync.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Worktree Runtime

> Isolated git worktree environments for parallel agent work

Worktree runtime uses [git worktrees](https://git-scm.com/docs/git-worktree) on your local machine.

Each workspace gets its own directory, but worktrees share the same `.git` directory as your main checkout.

## How worktrees work

A worktree is a separate directory on the same filesystem as the main repository.

* It has its own working tree (files on disk) and checkout state.
* It shares a `.git` with the main repository.

Because `.git` is shared, **commits created in any worktree are immediately visible to your other worktrees (including your main checkout).**

Worktrees aren’t locked to a branch. The agent can switch branches, enter detached HEAD, or create new branches as needed. If you want to constrain branching behavior, do it via your [instruction files](/agents/instruction-files).

## Filesystem layout

Worktree workspaces are stored in `~/.xum/src/<project-name>/<workspace-name>`.

Example layout:

```text theme={null}
~/.xum/src/
  my-project/
    improved-auth-ux/
    fix-ci-flakes/
```

## VS Code workspace file sync

To browse all of a project's worktrees from one VS Code or code-server window, set a `.code-workspace` file path per project in Settings → Runtimes (select the project scope). Xum keeps that file's folder list in sync as worktree workspaces are created, renamed, archived, and deleted.

Xum only manages folder entries under the project's worktree directory; folders you add yourself and everything outside the `folders` array (comments, `settings`/`extensions` blocks) are left untouched. When Xum adds or removes an entry it rewrites the `folders` array itself, so comments placed inside that array are not preserved.