Skip to content

wt: one git worktree per agent task

The problem

Two coding agents in one checkout edit the same files and switch branches under each other. git worktree add gives each its own folder and branch, but a fresh worktree has none of the files git ignores: no .env, no node_modules, no virtualenv. The agent cannot run the app. Cleanup goes wrong too: a merge lands on whatever branch the main checkout is on, or a tree is thrown away with uncommitted work in it.

The method

wt new NAME makes branch task/NAME in REPO-trees/NAME, then:

  • Finds the main repo from --git-common-dir, so running it inside a task tree still puts the new tree beside the main repo, not nested in the task tree.
  • Copies what git will not, picked by two git questions: untracked files matching the include patterns, then only those git really ignores.
git ls-files -z --others --ignored --exclude-from=patterns |
  git check-ignore -z --stdin          # .env, .env.*, .envrc, plus .wtinclude

A tracked .env.example comes from git; a loose untracked note is not copied. cp -p keeps a 600 secrets file at 600. - Installs by lockfile with the frozen flag: pnpm, bun, yarn, npm ci, uv, pip. - Starts the agent (AGENT, default claude) inside the tree.

The way back is guarded. wt merge refuses when the task tree has uncommitted or untracked work, when the main tree is dirty, or when it is on another branch; the base branch is fixed (WT_BASE, origin/HEAD, init.defaultBranch, else main/master), never "whatever is checked out". wt park acts only on a merged branch: it moves the folder to REPO-trees/.parked/, removes nothing, and drops the branch with git branch -d.

wt new fix-login "make the login form show errors"
wt diff fix-login
wt merge fix-login && wt park fix-login
AGENT=codex wt new tidy-css

Limits

  • Bash 3.2+, git 2.31+.
  • Dependencies install per tree (pnpm and bun share a store, so they cost least).
  • Ignored files are copied once, at creation.
  • Lockfiles at the repo root only.

Code

methods/wt/ in the methods repository: one Bash script, a README and a 51-check test.