freno-dev/marketing/drafts/agent-worktree-contention/copy.md

How do you manage worktrees when your agents end up waiting on each other?

Status: draft — awaiting sponsor fact-check (FRE-199 pair 3, internal target Thu 2026-11-12). Not publishable from drafts/. This page never names a product of ours and never names a competitor.

Usually, the worktrees are not what your agents are waiting on — the environment they share is. Two agents can sit in two worktrees of the same repo and still queue up behind one dev server, one test database, one docker compose stack. The fix that scales is to multiply the environment per worktree, not to orchestrate the waiting.

Why agents queue when the code doesn't

Git supports parallel work out of the box: git worktree add <path> <branch> creates a second working directory linked to the same repository — shared history, but its own HEAD, its own index, its own checked-out branch. Git even enforces the ownership half for you: it refuses to check out a branch into a second worktree while the first one holds it.

What git does not duplicate is everything the repo only points at: the dev server bound to port 3000, the database named after the project directory, the compose stack whose project name defaults to the folder you launched it from. Two agents in two worktrees that both bring up the same stack are two agents contending for one environment — and the queue looks like a worktree problem when it is an environment problem.

Practitioners who hit this converge on the same verdict. One, in a thread asking this exact question: the queue "comes from having one test env, so I'd multiply the env instead of orchestrating the waiting."

What to check or do

1. Give every worktree its own copy of the stack. Docker Compose exists for exactly this: it uses a project name to isolate environments from each other, and names "multiple copies of a single environment, useful for running stable copies for each feature branch" as a use case. Set a unique one per worktree — the -p flag has top precedence, or use name: in the compose file — and the port and container-name collisions disappear.
2. Anything that cannot be multiplied, serialise on purpose. One migration runner, one deploy target, one flaky hardware-in-the-loop device: put it behind a single serial step rather than letting two agents race it. A queue you chose is a queue you can reason about.
3. One branch, one worktree. Git already refuses to check out the same branch in two worktrees; keep it that way. Two agents on one branch is a merge conflict waiting for both of them to finish.
4. Remember a fresh worktree starts unconfigured. Env files, generated config and installed dependencies live in the worktree, not the repo — a new worktree is a new environment to set up, which is exactly why the per-worktree copy should be scripted, not hand-arranged.

One next step: find the resource your agents contend for most often — usually the test stack — and give it a per-worktree project name. The waiting usually resolves before any queueing tool is needed.

---

Fact-check table (not part of the page)

Every technical claim above, with its primary source. Claims about git and Docker Compose were verified against the live docs on 2026-11-05.

#	Claim in the page	Source
1	git worktree add <path> [<commit-ish>] creates a worktree "linked to the current repository, sharing everything except per-worktree files such as HEAD, index, etc."	git worktree docs — https://git-scm.com/docs/git-worktree (COMMANDS › add; fetched 2026-11-05)
2	add "refuses to create a new worktree when is a branch name and is already checked out by another worktree"	same page (OPTIONS › --force)
3	Compose "uses a project name to isolate environments from each other"; "multiple copies of a single environment, useful for running stable copies for each feature branch" is a named use case; precedence: -p flag > COMPOSE_PROJECT_NAME > name: attribute > directory basename	Docker Compose docs, "Specify a project name" — https://docs.docker.com/compose/how-tos/project-name/ (fetched 2026-11-05)
4	Anecdote: "The queue comes from having one test env, so I'd multiply the env instead of orchestrating the waiting"	r/ClaudeCode thread 1xlz2bs ("How do you manage worktrees when your agents end up waiting on each other?", 2026-11-02, u/Roland_culait / u/First-Painter7431), logged in drafts/listening.md Scan 6 #4. Quoted as one commenter's described practice, not a measurement.

Ban compliance: no product of ours named · no competitor named · no superlatives · no benchmark numbers · no invented testimonials (the anecdote is a real thread, described without handles) · no price · no roadmap dates.