Skip to content

Commit 117d4f2

Browse files
bokelleyclaude
andauthored
docs(adcp): document git worktree isolation pattern for parallel agents (#428)
* docs(adcp): add parallel agent isolation (git worktree) section to CLAUDE.md Documents the git worktree pattern for parallel agent isolation, including spawn checklist, .env and pre-commit setup steps, teardown, and branch naming convention. Closes #418. https://claude.ai/code/session_017TUh8WYUoUWzdxDQMPLM5t * fixup: use git-common-dir for .env copy; add CONDUCTOR.md cross-link Addresses pre-PR review blockers: replace unresolvable /path/to/repo-root placeholder with git rev-parse --git-common-dir to reliably locate the main worktree root, and add CONDUCTOR.md cross-reference. https://claude.ai/code/session_017TUh8WYUoUWzdxDQMPLM5t --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent a29b61f commit 117d4f2

1 file changed

Lines changed: 36 additions & 0 deletions

File tree

CLAUDE.md

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -149,6 +149,42 @@ pytest tests/ -v # Tests
149149

150150
All three must pass. CI runs them across Python 3.10–3.13; locally running on your current version catches most issues.
151151

152+
## Parallel Agent Isolation (git worktrees)
153+
154+
When multiple agents work in the same checkout simultaneously, they clobber each other's
155+
branches — there is no error, the work is silently lost. Use `git worktree` to give each
156+
agent an isolated checkout.
157+
158+
> **Note:** Conductor worktrees handle this automatically via `.conductor.json`
159+
> (runs `setup_conductor_env.py` + `pre-commit install` on create). Use the
160+
> manual steps below only for raw `git worktree` outside of Conductor.
161+
> See `CONDUCTOR.md` for Conductor-specific setup and troubleshooting.
162+
163+
**Create a worktree:**
164+
165+
```bash
166+
git worktree add /tmp/claude-issue-<N>-<slug> -b claude/issue-<N>-<slug> main
167+
```
168+
169+
**Setup checklist (run inside the new worktree):**
170+
171+
```bash
172+
cd /tmp/claude-issue-<N>-<slug>
173+
cp "$(git rev-parse --git-common-dir)/../.env" .env # .env is not inherited
174+
pre-commit install # hooks are not inherited from parent worktree
175+
pip install -e .[dev] # install in this worktree's context
176+
```
177+
178+
**Teardown (after branch is merged):**
179+
180+
```bash
181+
git worktree remove /tmp/claude-issue-<N>-<slug>
182+
# or: git worktree prune # removes all stale worktrees at once
183+
```
184+
185+
**Branch naming:** always follow `claude/issue-<N>-<short-slug>` — branch-protection
186+
rules enforce this pattern and PRs from non-conforming names may be rejected.
187+
152188
## Additional Important Reminders
153189

154190
**NEVER**:

0 commit comments

Comments
 (0)