Parallel agents and git worktrees

This started with a commit that had someone else's files in it. Two Claude sessions were working in the same repo, one ran git add -A, and the other one's untracked work went along for the ride.

Why it happens

Every session sees the whole working directory. Two sessions sharing one means:

• git add -A picks up the other one's uncommitted files
• edits to the same file race each other
• a branch switch in one changes the ground under the other

A git worktree is a second working directory on the same repository. The .git is shared, the files are not, so one agent cannot see what another has not committed.

Each agent commits on its own branch, from its own directory. They meet in the history, where a merge is a decision and not an accident.

How I work now

One worktree per line of work, not per session. Several sessions in one worktree are fine, since they are working on the same thing. The isolation only matters between lines of work that are independent.

git worktree add ../myrepo-search -b feat/search
cd ../myrepo-search && claude

I have a small shell function that does that, names the tmux window after the scope, and a second one that removes the worktree and the branch when the work is merged.

One branch is one change is one pull request. When it is merged, the branch is done: remove it and start a new one. Clearing the session and carrying on in the same worktree is how the next pull request ends up with two things in it. The exception is review feedback on a pull request that is still open; then I stay and fix it there.

Three kinds of windows

With a lot of tmux windows on one project, I think of them as:

1. Conversation. Planning, questions, talking through a bug. No git. The main tree is fine.
2. Implementation. A feature or refactor that will take more than one commit. Its own worktree.
3. Quick fix. One commit. A branch is enough if nobody else is in the tree; otherwise a worktree.

Window names are short and say the scope, not the action: search-perf, mobile-ux. No project prefix; the folder already says that.

The rule that would have saved me

Never git add -A or git commit -a unless the working directory is known to be clean. Name the paths:

git add src/lib/foo.ts src/components/Bar.tsx
git show HEAD --stat

The second line is the check: only the files you meant are in the commit. A hook at session start also prints git status and warns about untracked files I don't recognise, since that is usually a sign another agent is in the tree.