Distilled from Cole Medin's "Parallel Claude Code + Git Worktrees" (2026-04-23). Five pillars + operational blockers + feedback loop. Run 3–10 agent sessions in parallel without human bottleneck.
10x > 2x. 2x throughput lets you cheat with human babysitting. 10x forces a system that survives without you. Design for 10x from day one; the constraint is productive.
Two boundary artifacts drive everything: - Input: GitHub issue (or Linear/Jira ticket) — the spec - Output: Pull request — the review artifact
Agents read an issue, open a PR. Fan-out, handoff, and comparison become trivial because every session has the same contract.
| # | Pillar | Rule |
|---|---|---|
| 1 | Issue-as-spec | Every parallel session starts by pointing at an issue number. No free-form prompts. |
| 2 | Worktree-per-task | One isolated worktree per in-flight task. claude -w <name> handles it natively. |
| 3 | Plan → Build → Validate loop | Agent plans in the issue thread, builds in the worktree, validates before opening PR. |
| 4 | Fresh-context review | Reviewer MUST run in a new context. Writer's chat history biases judgment — "kid grading own homework." |
| 5 | Self-healing feedback | Review finds a bug → fix the rule/skill/CLAUDE.md that allowed it, not just the code. |
| Layer | Problem | Fix |
|---|---|---|
| Codebase | Agents stepping on each other's files | git worktree per task |
| Dependencies | Agent wastes context on npm install |
Pre-install via setup script before handoff |
| Runtime port | Two dev servers on :3000 | Hash worktree name → deterministic port offset from base (e.g., 4000 → 4107) |
| Database / schema | Migrations collide, fixtures diverge | Neon branch per worktree (full table + data copy), or SQLite-per-worktree for local |
| Context window | Reviewer inherits writer's bias | /clear before review; separate session; different model family preferred |
A custom launcher script (w.sh / w.ps1) is the integration point. Responsibilities:
1. git worktree add under .claude/worktrees/<name>/
2. Install deps (npm ci / equivalent) so agent doesn't burn context on it
3. Create DB branch (Neon API call) or copy SQLite file
4. Assign port via name hash
5. Emit env vars / config so dev server comes up correctly
This pattern gives worktree support to any coding agent — Claude Code, Aider, Cursor,
Codex — not only those with native --worktree flags.
/model switches per-session. Heavy implementation = top model. Code analysis,
research, review = cheaper tier (Haiku/Sonnet)./review-pr in a fresh context window (Claude Code native, data-mines
the PR tied to current branch)./codex adversarial-review (Codex plugin, different model family).In Cole's demo: Claude passed 5/5 PRs, Codex flagged 4/5 as "needs attention." Redundant same-family reviewers miss the same things.
Rule: every bug fixed in a PR also gets a matching fix in the AI layer.
| Bug class | Fix location |
|---|---|
| Agent misunderstood requirement | Rewrite issue template / add example to CLAUDE.md |
| Agent used wrong pattern | Update skill or add rule in ~/.claude/rules/ |
| Agent skipped validation | Add PreToolUse hook or checklist in skill |
| Reviewer missed issue | Expand /review-pr prompt, add adversarial reviewer |
PR pileup = human bottleneck = signal to invest in the self-healing layer. Never skim reviews to catch up — that defers the work, doesn't eliminate it.
[ ] Every task has a GitHub issue with acceptance criteria
[ ] Launcher script provisions: worktree + deps + DB branch + port
[ ] Agent prompted with issue number only (not free-form description)
[ ] Each agent session opens a PR on completion (never merges directly)
[ ] Reviewer runs in /clear'd context, separate model if possible
[ ] Codex adversarial-review runs before human review
[ ] Every bug found → identify AI-layer fix before closing PR
[ ] Token routing verified: cheap models for analysis/review, top for implementation
/worktree-spawn skill candidate: Cole's w.sh responsibilities (worktree,
deps, DB branch, port hash) map to a shareable fleet skill. Currently each repo
reinvents this.~/.claude/rules/08-task-protocol.md backlog files
already match the pattern — task file = issue, Resolution block = PR merge. Missing
piece is the parallel orchestrator on top./codex adversarial-review plugin for Arsenal review
stack. Cross-family reviewer = structural bias reduction.# w.sh — portable parallel worktree launcher
NAME="$1"; ISSUE="$2"
BASE_PORT=4000
PORT=$((BASE_PORT + $(echo -n "$NAME" | cksum | cut -d' ' -f1) % 1000))
git worktree add ".claude/worktrees/$NAME" -b "feat/$NAME"
cd ".claude/worktrees/$NAME"
npm ci
# neon branches create --parent main --name "$NAME" # if using Neon
echo "PORT=$PORT" > .env.local
claude -w "$NAME" --prompt "Implement GitHub issue #$ISSUE. Open PR when done."
Adapt port-hashing, DB provisioning, and agent invocation to the target stack.
research/youtube/notes/yt-rFGlJ4oIlhw-...md