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/repogets 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 refactorsetup-worktree does both conventions for you:
- Pins down which repo you mean, and asks when the home sits above several.
- Creates the sibling worktree on a new branch.
- Copies the gitignored local files from the main checkout.
- 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:
| Verdict | Means |
|---|---|
deletable | The branch's content is already in the base: merged, squash-merged, or no commits of its own |
uncommitted, unpushed | It holds real work |
pushed-unmerged | Safe on a remote but not landed, so likely in review |
missing | Registered in git, but the folder is gone |
base | A 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.
Pull requests
Review a teammate's PR, answer the review on yours, present yours, and sweep everything on GitHub waiting on you. You paste every comment; only your own PR's description is applied for you, once you approve it.
Specs and plans
Turn an intent into a spec before code, design a bespoke workflow for large work, and keep a decision trail you can audit later.