Worktree Isolation

Using separate git worktrees to give each parallel agent its own filesystem checkout. Agents literally cannot touch each other’s files. The ToS-compliant, ho…

Worktree Isolation

Using separate git worktrees to give each parallel agent its own filesystem checkout. Agents literally cannot touch each other’s files. The ToS-compliant, host-native alternative to container-based sandboxing.

---

What a Git Worktree Is

A git worktree is a second (or third, Nth) checkout of the same repository in a different directory. All worktrees share the same .git object store — commits, history, refs — but each has its own working tree and HEAD.

# Create worktree on a new branch
git worktree add /tmp/task-auth -b agent/auth-middleware

# Agent works in /tmp/task-auth — isolated from main checkout
# When done:
git worktree remove /tmp/task-auth
git worktree prune  # clean up stale entries

One repo, multiple simultaneous checkouts, zero file conflicts between agents.

---

Why Agents Need It

Without worktree isolation, parallel agents editing the same repo share a working directory. Agent A edits src/auth.ts. Agent B, working on a different task, reads src/auth.ts and gets A’s half-finished state. Both commit. Conflict.

With worktree isolation:

• Each agent has its own filesystem state
• Agents can’t observe each other’s in-progress edits
• Each agent starts from a known clean commit
• Merge happens after each agent completes — not mid-task

This is also what makes Context Compression Strategies clear-over-compact safe: the agent starts fresh each task, but state is preserved in commits and branch, not in agent memory.

---

Scope Overlap Detection

The precondition for safe worktree isolation is non-overlapping file scope between agents. Before assigning tasks to parallel agents, check that their target directories don’t overlap:

✓ Agent A: src/auth/           Agent B: src/payments/       — safe
✗ Agent A: src/domains/        Agent B: src/domains/auth/   — overlap: B is inside A's scope

Scope overlap causes merge conflicts even with worktree isolation — agents edit different checkouts of the same files, then both try to merge. Scope overlap detection is a required orchestration primitive.

---

Merge Protocol

Merge-before-cleanup rule: always merge the worktree branch before removing the worktree. Removing first loses any uncommitted or unmerged work.

# Correct order
git merge agent/auth-middleware   # merge first
git worktree remove /tmp/task-auth  # then clean up
git branch -d agent/auth-middleware

Merge strategy after isolation depends on Branch Strategy for Agents:

• head — merge directly to current HEAD (low risk, non-overlapping files)
• merge-to-head — standard merge (default for parallel work)
• branch — open a PR for human review before merging (security changes, shared interfaces)

---

Relation to ToS and Sandboxing

Agentic Sandbox Controls recommends OS-level sandboxing (containers, Bubblewrap) per the NVIDIA AI Red Team guidance. But Anthropic’s ToS restricts Claude Code subscription keys inside Docker containers.

Worktree isolation is the ToS-compliant host-native alternative:

Mechanism	Isolation type	ToS-compliant	Requires container
Docker/container	Full OS isolation	No (subscription key)	Yes
Worktree	Filesystem isolation	Yes	No
permissions.allow/permissions.deny	Tool-level restriction	Yes	No

Dangeresque (host-native) uses worktrees + tool filtering. SandCastle runs Claude on the host (worktree isolation) and only containers for tool execution — Claude itself never runs inside Docker. Note: CC’s native settings.json schema uses permissions.allow/permissions.deny, not the older allowedTools/disallowedTools names. See Claude Code Permissions Settings.

---

Implementations

Tool	How it uses worktrees
Dangeresque	One worktree per task; worker runs in isolation; adversarial reviewer reads result
SandCastle	Worktree + sandboxed container per task; branch strategy as a first-class parameter
Agent Subagents	isolation: "worktree" in frontmatter; cleaned up automatically if no changes

---

Per-Task vs Per-Agent

The fundamental architectural decision when assigning worktrees:

Factor	Worktree-Per-Task	Worktree-Per-Agent
Task duration	Short (minutes to ~1 hour)	Long (multi-hour sessions)
Cache reuse	None; fresh install per task	Warm; dependencies persist
Cleanup model	Destroy after each task	Destroy after session ends
Best fit	Ephemeral code generation, one-shot refactors	Dedicated test writers, ongoing refactoring agents

Default: worktree-per-task. Worktree-per-agent only when the agent persists across multiple tasks and benefits from warm dependency caches or accumulated environment state (e.g., a long-running specialist agent keeping a pre-compiled build warm).

---

Runtime Isolation Gap

Worktrees solve filesystem conflicts only. They do not provide network or process isolation.

Two agents in separate worktrees still collide on:

• Port numbers when both start a dev server on :3000
• Shared databases and test state
• Build caches and configuration registries

Mitigations:

• Deterministic port assignment from branch name hash: PORT=$(( 3100 + $(echo "${BRANCH_NAME}" | cksum | cut -d' ' -f1) % 6899 ))
• Galactic (github.com/idolaman/galactic) — assigns a unique local IP per worktree (127.0.0.2, 127.0.0.3, etc.) so multiple backends run without port juggling
• Block’s agent-task-queue — FIFO coordination for expensive shared operations like test runners; prevents multiple agents from concurrently triggering ./gradlew test
• Composite pattern: worktrees for git isolation + containers (Dagger Container-Use) for runtime isolation; full isolation at both layers

---

Operational Details

Lock while agent runs

git worktree lock --reason "Agent running" .trees/TASK-123
# prevents accidental removal while agent is active

git worktree unlock .trees/TASK-123
git worktree remove .trees/TASK-123
git worktree prune

Conflict resolution recording

git config rerere.enabled true
# Records conflict resolutions; auto-reapplies on identical recurrence
# Valuable when agents touch the same files in sequential waves

Sparse checkout (monorepos)

Constrain worktree to files the agent actually needs:

git worktree add .trees/TASK-123 -b agent/TASK-123 origin/main
cd .trees/TASK-123
git sparse-checkout set src/payments/ tests/payments/

---

Fresh Context Window Per Task

Each worktree task gets a fresh agent session — no accumulated context from prior tasks. This is the mechanical basis for Context Compression Strategies clear-over-compact in AFK workflows:

task 1 → worktree A → agent (fresh context) → commit → merge → worktree removed
task 2 → worktree B → agent (fresh context) → commit → merge → worktree removed

State carried between tasks lives in: commits, branch history, .agents/decisions.md, issue files — not in agent memory. This is what Pocock means by “make clearing safe, then prefer clearing.”

---

Reference Orchestrators Using Worktrees

Tool	How it uses worktrees
Augment Code Intent	Coordinator → Specialists (Investigate/Implement/Verify/Critique/Debug/Review) → Verifier; living spec as shared coordination artifact; BYOA (Claude Code/Codex/OpenCode as implementers)
Switchman	File claiming; prevents logical scope overlap upfront
Overstory (jayminwest/overstory)	FIFO merge queue + watchdog for larger agent fleets
Galactic (idolaman/galactic)	Per-worktree local IP (127.0.0.2, 127.0.0.3…)
Dagger Container-Use	Worktrees + container runtime for full isolation at both layers

Related Pages

• Shared Task Queue (Cross-Worktree) — filesystem inbox with atomic claim semantics; how agents discover tasks at startup across worktrees
• Branch Strategy for Agents — merge strategy after worktree work completes
• Agentic Sandbox Controls — ToS constraint driving host-native isolation
• Context Compression Strategies — clear-over-compact; worktrees make clearing safe
• Dangeresque — lightweight host-native orchestrator using worktrees
• SandCastle — TypeScript lib; worktree + container combination
• Agent Subagents — isolation: "worktree" parameter