Docs

Worktrees

A Git worktree is a second working directory backed by the same repository, checked out to its own branch. Orbit treats one as a first-class workspace, so two branches can run side by side with two agents.

What a worktree is

Worktrees let you check out more than one branch at a time from a single repository. In Orbit, opening a worktree makes it the active workspace: the Explorer, terminal, Git page, Review pane, and every new session all run inside it, on its branch.

Names, branches, and paths

Orbit keeps three identities separate and never derives one from another:

name    113
branch  feature/issue-113
path    ~/Projects/my-project/.wt/113
  • The name is what you choose; it only needs to be one safe path component.
  • The branch is the Git branch checked out there.
  • The path is always <worktree root>/<name>.

Creating one

  1. Open the Worktrees page — from the command palette, or from the status bar's Work in chip.
  2. Choose New worktree, then enter a name and pick an existing branch or create a new one. A new branch defaults to a slug of the name.
  3. Create it. Orbit runs git worktree add and, by default, opens the result as the active workspace.

The Worktrees page also lists every linked worktree and supports open, rename, move, lock / unlock, remove, and the repository-wide prune and repair actions.

Where worktrees are created

New worktrees go under the worktree root, which defaults to .wt inside the repository. Precedence:

  • Per repository — .orbit/worktree.json overrides the directory and setup script for that project.
  • Global — ~/.orbit-pi/worktrees.json holds the default directory and setup script, plus the automatic-create options.
{
  "directory": ".wt",
  "setup_script": ".orbit/worktree-setup.sh",
  "run_setup_auto": true,
  "open_after_create": true
}

~ expands to your home directory, and absolute paths are allowed. The repository file can set only directory and setup_script; the automatic-create booleans are global.

Setup scripts

A repository can carry a setup script that runs inside the new worktree right after it is created — linking a .env, sharing node_modules, warming a build cache, and so on. Orbit hardcodes none of that; the script is entirely yours.

The script receives two environment variables:

ORBIT_ROOT_PATH=/Users/you/project
ORBIT_WORKTREE_PATH=/Users/you/project/.wt/113
  • The default path is .orbit/worktree-setup.sh, configurable per repository and globally.
  • It runs on a background executor and its output is captured, so the UI stays responsive. You can retry it or open the worktree even if it fails — a failed setup never removes the worktree.
  • Scripts run arbitrary commands, so the first run in a repository is an explicit confirmation.

Switching workspaces

The status bar's Work in chip switches the active workspace between Local (the main checkout) and any linked worktree, and offers a quick create for a new one. Because a worktree is just a workspace path, sessions opened while it is active are rooted there and appear under its own project in the sidebar.

PreviousSessionsNextMCP servers