Skip to main content
Worktree runtime uses git worktrees 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.

​
Filesystem layout

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

​
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.