Isolate

Isolate

One tree per task. The failure this prevents has no error message: two agents in one working copy overwrite each other's edits, and git reports nothing, because from git's side the second write is just the current state of the file.

Before creating anything, check nobody is already on it

git ls-remote --heads origin
gh pr list --state all --limit 30

Two commands, seconds each. A branch that already exists under the name you were about to create is the cheapest possible warning that someone is on the same problem. Read that branch before renaming around it, and if the work is duplicated keep the better implementation rather than yours.

But a branch name is not evidence about its content. Test whether its commit is an ancestor of the default branch, and run a control so a uniform answer cannot pass as a finding:

git merge-base --is-ancestor origin/<branch> origin/main   # exit 0 = already landed
git merge-base --is-ancestor HEAD origin/main              # control, expect 1

[measured 2026-09-02] a branch named fix/always-on-without-a-trigger was the only match for a search about skill triggers. It had already landed, and its tip commit was a telemetry path fix. The name matched the search and nothing else did.

Neither command above can see unpushed work

Both read the REMOTE. Where commits stay local until someone says push, which is the default in this estate, the normal state of work in progress is invisible to both. So the scope check as written is blind to precisely the case it exists for.

Add the local probe, and run it against the repo's MAIN CLONE rather than your own tree, because that is where another session's finished-but-unpushed work sits:

git -C <main-clone> rev-list --left-right --count origin/main...HEAD
git -C <main-clone> log --oneline origin/main..HEAD
git -C <main-clone> status --porcelain

The first prints behind<TAB>ahead. A non-zero right-hand number means finished work exists that no worktree cut from origin/main can see, including yours. The third says whether someone is still typing in it.

[measured 2026-09-03] two sessions wrote the same layout gate for one repo within an hour. The remote showed nothing, because the first session's gate AND its fix for the underlying defect were committed locally and never pushed: six commits ahead, zero behind. From any worktree the defect still looked open, and the second session's evidence that "it does not exist" was correct about origin/main and wrong about the repo.

Nothing surfaced it. The two sessions found out because one sent the other an unsolicited message about a patch, and the reconciliation took four exchanges because the first quoted line numbers without naming a ref. A tracked file has as many current values as there are checkouts.

Two habits follow, and the second is the one that generalises. Name the ref in any claim about a file, so "line 1867" becomes "line 1867 of local main at 87f1ce7f". And re-fetch before you ACT, not before you send: that same measurement was two commits stale by the time it was read, because the clone was being actively worked while the message sat in a queue.

Create the tree

git fetch origin
git worktree add .claude/worktrees/<slug> -b <slug> origin/main

Branch from the remote default branch, not from local main, which may be behind or may carry another session's uncommitted work.

Unless your work sits on unpushed local commits. Then branch from HEAD and say so, because origin/main does not contain them and the tree would silently start without what you are building on. One command decides it:

git log --oneline origin/main..HEAD

Nothing printed means origin/main is safe. Anything printed is the list of commits you would have lost.

.claude/worktrees/ is the convention because it is gitignored, so the trees never appear as untracked files in the parent clone.

A fresh worktree is not a working checkout

git worktree add copies the tracked tree and nothing else. Two things are missing and both fail in ways that look like a bug in your change:

• Gitignored env files. Copy .env.local and siblings from the main clone. Without them a dev server starts with zero env injected, the app never mounts, and every browser check fails against a blank page.
• node_modules, but only if the repo has dependencies. A worktree cut from an older base, or reusing the parent's install, surfaces import errors for dependencies added since. Count them before installing: a repo with zero deps needs no install, and running one anyway is a minute spent per worktree.

Check both before concluding anything about the code:

ls -a .claude/worktrees/<slug> | grep -c '^\.env' || echo "0 env files, copy them"

Never touch a tree you did not create

Do not git checkout in a clone another session is using. Run git status first: a dirty tree you did not dirty means someone is in there, and a checkout carries their uncommitted work onto your branch without warning them.

The same applies to another agent's worktree, its branch, and its uncommitted work. If you need what is on it, read it; do not switch into it.

When to skip this

One checkout, one session, one-line change. The threshold is whether anyone else could be in the tree while you work, not how large the change is.

If you skip it, say so. A step skipped and named is a decision; a step skipped silently is indistinguishable from one forgotten.

Finish by removing it

git worktree remove .claude/worktrees/<slug>
git worktree list

Only after the branch is merged or the work is abandoned. A stale worktree holds a branch checked out, so the next session that tries to use that branch gets a refusal it has no context for.