AgentLayer▸docs
Engineering

Worktrees

Parallel agents on one repo with zero collisions, and a skill that creates and bootstraps the checkout for you.

A git worktree checks out a second working copy of the same repo into a separate folder, on its own branch, sharing one .git. Agent A refactors on feature-x while Agent B fixes a bug on bugfix-y, and nobody's files change under them.

Two conventions

  • Siblings, never nested. The main checkout at ~/Developer/acme/repo gets a worktree at ~/Developer/acme/repo-my-feature. A nested worktree lands under a tracked path and pollutes the parent's working tree.
  • Bootstrap before coding. A fresh worktree has no gitignored local files (.env*, .claude/settings.local.json), no installed deps, no built packages.

Ask for one

make a worktree for the billing refactor

setup-worktree does both conventions for you:

  1. Pins down which repo you mean, and asks when the home sits above several.
  2. Creates the sibling worktree on a new branch.
  3. Copies the gitignored local files from the main checkout.
  4. Detects the package manager (bun, pnpm, yarn, npm), installs, and runs the build script.

It offers to add the worktree to a sibling .code-workspace if one exists, and can give the worktree its own database through database_fork.

Underneath, the setup_worktree MCP tool runs outside the host's shell sandbox so git worktree add can make the writes the sandbox blocks. The same logic is on the CLI: bun "<plugin root>/src/cli.ts" worktree <repoPath> --branch=....

Audit

which worktrees do I have? which can I delete?

The read-only list_worktrees tool reports each worktree with a verdict:

VerdictMeans
deletableThe branch's content is already in the base: merged, squash-merged, or no commits of its own
uncommitted, unpushedIt holds real work
pushed-unmergedSafe on a remote but not landed, so likely in review
missingRegistered in git, but the folder is gone
baseA worktree on dev, develop, main or master. It is never removed: remove_worktree refuses it, and the teardown leaves it out

How stale a worktree is comes with it as an age and how far it sits behind the base. remove_worktree is never pre-granted, so every deletion confirms.

Pair worktrees with cmux: one workspace per worktree, one agent per workspace.

Cleanup

tear down the worktrees that are safe to delete.

The audit ends by offering a full teardown of the deletable worktrees only, one choice per worktree. A full teardown removes four things: the workspace entry, the worktree, its branch, and its database fork. A plain "drop" without "full" keeps the branch.

Two kinds of worktree are never offered:

  • one with uncommitted or unpushed work, or still in review;
  • one a session worked in during the last day. The check reads each session's working directory, so a session you launched from the agent home still counts.

You confirm once, and remove_worktree's own permission prompt is the second gate.

On this page