e12a063aa9
Pair 3 (internal target Thu 2026-11-12, six days early): - agent-worktree-contention — 'How do you manage worktrees when your agents end up waiting on each other?' (backlog 1xlz2bs, Scan 6 #4); git worktree + Docker Compose project-name docs fetched and read 2026-11-05. - agent-keeps-asking — 'Why does your coding agent keep stopping to ask you questions?' (handback cluster: 1xlfqmo, 1xk0ghj, 1xlxw0q); permission + hooks claims re-verified live 2026-11-05 against code.claude.com; the 1xlfqmo poster's measurement figures deliberately not cited. Pitch narrowed per CTO reopening verdict: trial→paid placeholder deleted (FRE-202 cohort too young; ratio waits for FRE-197), second breakage chosen (NOOK-815 uninvoked suite), any count named as activations, downloads never quoted.
73 lines
4.7 KiB
Markdown
73 lines
4.7 KiB
Markdown
# 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 <commit-ish> 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.
|