ADR-006: Git Worktree Isolation Per Agent

Status

Accepted

Context

Multiple agents work on the same repository concurrently. They must not interfere with each other's file changes.

Decision

Each agent gets its own git worktree branching from the base commit. The supervisor also gets its own worktree for integration.

Branch Naming

  • Agent branches: swarm/<session-id>/<agent-name>
  • Supervisor branch: swarm/<session-id>/supervisor
  • Beads branch: swarm/<session-id>/beads (shared, optimistic concurrency)

Worktree Location

Worktrees are created under .swarm/worktrees/<agent-name>/.

Lifecycle

  1. swarm start: Create worktrees for all agents + supervisor from HEAD.
  2. During session: Agents commit to their own branches freely.
  3. swarm stop:
    • Auto-commit any dirty worktrees.
    • Based on stop mode (merge/squash/discard), combine branches.
    • Remove worktrees and delete branches.

Locking

Worktrees are locked (git worktree lock) during active sessions to prevent accidental removal.

Alternatives Considered

AlternativeWhy rejected
Separate clonesWastes disk space, slow
Shared working directory with stashRace conditions, impossible with concurrent agents
Docker containers per agentHeavy, slow startup

Consequences

  • Requires git >= 2.20 for reliable worktree support.
  • .swarm/ must be in .git/info/exclude to avoid tracking.
  • Recovery must handle orphaned worktrees from crashed sessions.
  • Worktree creation/removal is async (tokio::process::Command).

Stop Modes

ModeBehavior
--mergeMerge each agent branch into the original branch (default)
--squashSquash-merge each agent's work into a single commit
--discardDelete branches without merging