Worktree
Published Updated
What is Worktree?
In Orbit, a worktree is a separate Git working copy that Orbit creates automatically so a piece of work can run in isolation: one per sandbox session, Coordinator subtask or Benchmark configuration.
Separate git working copies Orbit creates for parallel work — Coordinator subtasks, Sandbox sessions, Benchmark runs. Auto-managed without manual git commands.
When Orbit needs isolated parallel work, it creates git worktrees automatically. Coordinator Mode creates one per subtask. Sandbox sessions create one per session. Benchmark Mode creates one per model configuration. When work completes and is promoted/merged/cleaned up, worktrees are removed. You don't manually manage them.
How it relates to Orbit
Orbit uses per-prompt worktrees for sandbox sessions so a run can be reviewed separately from the default branch. See Sandbox for details.
When you would use it
You don't directly use Orbit-created worktrees — they exist behind the scenes for the features that need them. Familiarity with the concept helps when debugging or inspecting state manually.
Common operations
- Running parallel Coordinator subtasks safely
- Isolating sandbox experimentation
- Running benchmark configurations independently
Frequently asked questions
Do I have to manage Orbit’s worktrees myself?
No. Orbit creates them when isolated work starts and removes them when the work is promoted, merged or discarded.
What happens to a worktree left behind?
Orbit watches for orphaned worktrees, branches and session rows and offers Clean Up or Ignore for each under Settings → Queue & Sessions → Sandbox. See Sandbox Issues.
Is an Orbit worktree different from a Git worktree?
No, it is a standard Git worktree. The Orbit term just refers to the ones Orbit creates and manages for you.
Related terms
Dashed terms are named in the source but do not have a page here yet.
Where this is taught
No learning path uses this term yet. Browse the Learning Atlas for guided sequences through related ideas.