Worktrees

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 Kevin

make a worktree for the billing refactor

setup-worktree pins down which repo you mean (it 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: kevin worktree <repoPath> --branch=....

Audit

which worktrees do I have? which can I delete?

The read-only list_worktrees triage reports each worktree with a verdict: merged, stale, or active. 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: the workspace entry, the worktree, its branch, and its database fork. Anything with uncommitted or unpushed work, or still in review, is never offered, and neither is a worktree 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. A plain "drop" without "full" keeps the branch.