Git worktrees for parallel agents, only where they can collide

Context

Once engineers run several agent chats at once, a single checkout becomes shared mutable state. Two chats sharing one checkout share one branch: when one runs a checkout, the other doesn’t notice, keeps editing, and commits to the wrong branch.

The standard fix is a git worktree per branch: a separate folder for each branch, sharing one history. Cloud agents would be the other way to run work in parallel, but they weren’t available to the team yet.

Options considered

• A worktree for every ticket. Simple to explain, and my first version did exactly this.
• A worktree only where the failure can happen.

Decision

Within a day I reversed my first version. The collision has one precise cause: two chats committing in the same folder at the same time. Ticket size alone isn’t the test. So a worktree is offered, not required, and only when the work will commit and is either multi-day (roughly two points or more), likely to overlap with another chat, or starting in a folder that holds someone else’s uncommitted work.

• Read-only work never needs one. Investigating, planning, triaging, and reviewing never switch branches or commit, however many tickets they cover.
• Short tickets branch in place. Parallel work inside one ticket uses helper agents from the same chat.
• Isolate what each branch changes; share what should be identical. Each worktree gets its own Python environment, because a shared one breaks when a branch changes its requirements. Credential files are linked rather than copied, so renewing a token in one place renews it everywhere, and only files git already ignores are linked.
• Leave the last keystroke to a person. There’s no documented way for a script to open an agent chat in a chosen folder, so the tooling automates up to a prompt link and a person presses Enter.

Consequences

• A shared setup script works for the IDE’s built-in worktree mode and for terminal users. Helper scripts create and remove worktrees and refuse names that aren’t ticket keys.
• Testing found traps no amount of reading would have: an IDE branch menu that switches the main clone’s branch, worktree branches named by the tool rather than the ticket, old worktrees deleted past a per-machine cap, and squash merges that leave git unable to tell merged from unmerged. The cleanup script asks GitHub instead and refuses to delete anything it can’t confirm.
• The ignore rules for credential files became a pattern instead of a hand-kept list, after a few credential files turned out to have fallen off it.
• The pull request opened on October 2, 2026 and shipped that month. It was verified on macOS only, and I said so in the PR.
• The same pattern runs my personal Unreal Engine game, where parallel agent “lanes” each work in their own worktree.
• A related lesson the same week: on September 24 a sprint opened with one engineer carrying about seven times what fit in ten days, because estimates assumed unassisted work. Re-basing a point to one day of an engineer paired with an LLM brought it to about seven points.