How Git Worktrees Enable Agent Isolation in SwarmForge

SwarmForge isolates AI agents by assigning each role its own Git worktree under the .worktrees/ directory, creating separate working directories that share the same Git history to prevent file conflicts while maintaining a single source of truth.

SwarmForge, the multi-agent orchestration framework from unclebob/swarm-forge, leverages Git worktrees to provide filesystem-level isolation between concurrent AI agents. Unlike separate repository clones, worktrees allow each agent to operate in its own sandbox while remaining connected to a unified Git history. This architecture ensures that agents can modify files, commit changes, and generate handoffs without interfering with each other's working state.

Worktree-Based Isolation Architecture

The .worktrees Directory Structure

Each agent receives a dedicated subdirectory under .worktrees/. For a role named coder, SwarmForge creates .worktrees/coder as an independent checkout of the repository.

Shared History, Independent Worktrees

Because worktrees reference the same underlying object database, agents share consistent commit SHA references across the entire project. This enables reliable handoff coordination where one agent can reference another's commit hash, even though their file modifications remain isolated in separate directories.

The prepare-worktrees! Orchestration Function

According to the source code in swarmforge/scripts/swarmforge.bb, the prepare-worktrees! function handles worktree provisioning during startup. Lines 2124-2129 execute the Git command that creates isolated checkouts:

(defn prepare-worktrees! [ctx]
  (doseq [row (:roles ctx)
          :let [worktree-name (:worktree-name row)
                worktree-path (:worktree-path row)
                branch-name (str "swarmforge-" worktree-name)]
          :when (not (#{"none" "master"} worktree-name))]
    (when-not (or (fs/exists? (fs/path worktree-path ".git"))
                  (fs/directory? (fs/path worktree-path ".git")))
      (sh "git" "-C" (str (:working-dir ctx))
          "worktree" "add" "--force" "-B" branch-name
          (str worktree-path) "HEAD"))))

This function iterates through role definitions and creates branches prefixed with swarmforge- for each worktree. The command git -C <working-dir> worktree add --force -B swarmforge-<worktree> <worktree-path> HEAD establishes the isolated checkout.

Role Configuration in swarmforge.conf

Agent-to-worktree mappings reside in swarmforge/swarmforge.conf. Each line declares a window, role name, backend, and worktree designation:

window coder codex coder

This configuration creates .worktrees/coder and launches the coder agent using the Codex backend within that directory. The fourth column determines the worktree name used by the orchestration engine.

Special Worktree Names: master and none

Not all roles require isolation. Lines 72-78 of swarmforge/scripts/swarmforge.bb specify two reserved worktree names that bypass worktree creation:

• master: The agent runs directly in the main repository checkout
• none: The agent runs without worktree isolation

For these special cases, SwarmForge skips the git worktree add command and executes the agent in the primary working directory or without filesystem isolation.

Agent Execution and Runtime Isolation

During agent launch (lines 188-191), SwarmForge changes into the designated worktree path before invoking the backend:

{:worktree-path worktree-path
 :command (str "cd " worktree-path " && " backend-command)}

This ensures that tools like codex or claude operate exclusively within the agent's assigned directory. Filesystem modifications remain confined to that worktree, preventing cross-agent contamination while allowing standard Git operations.

Benefits of Git Worktrees for Multi-Agent Systems

Filesystem-Level Sandboxing

Worktrees provide hard isolation at the operating system level—each agent sees only its own directory tree, eliminating race conditions on shared files.

Lightweight Resource Usage

Unlike Docker containers or repository clones, worktrees share the same .git object database, minimizing disk overhead while maintaining complete working directory independence.

Native Git Handoff Support

Because all worktrees belong to the same repository, agents can reference specific commit SHAs when handing off tasks. One agent's commit is immediately available to others without pushes or pulls between separate repositories.

Summary

• SwarmForge creates isolated agent environments using Git worktrees under .worktrees/ rather than separate repository clones
• The prepare-worktrees! function in swarmforge/scripts/swarmforge.bb generates branches prefixed with swarmforge- and executes git worktree add for each configured role
• Role configurations in swarmforge.conf map agents to specific worktrees using the fourth column of each window definition
• Special worktree names master and none allow agents to run in the main repository or without isolation, as implemented in lines 72-78
• Worktrees enable clean handoff coordination through shared Git history while maintaining independent working directories for filesystem isolation

Frequently Asked Questions

Do SwarmForge agents share the same Git history when using worktrees?

Yes. Git worktrees share the underlying object database and refs, meaning all agents operate on the same repository history. This allows agents to reference each other's commits directly using SHA hashes, facilitating reliable handoff protocols without requiring pushes to remote servers.

What happens if I configure a role with worktree name "master"?

When a role specifies master as its worktree name, SwarmForge skips worktree creation entirely and runs the agent directly in the main repository checkout. This is useful for coordinator or overseer roles that need visibility across the entire project structure rather than an isolated subdirectory.

How does SwarmForge handle worktree conflicts during startup?

The prepare-worktrees! function checks for existing Git repositories in the target path before creation. If a .git file or directory exists at the worktree path, SwarmForge skips the git worktree add command, preventing conflicts with existing checkouts while ensuring idempotent startup behavior.

Can agents modify files in other worktrees?

No. Standard Unix filesystem permissions prevent agents from accessing sibling worktrees unless explicitly configured otherwise. Each agent's process starts with a working directory inside its assigned worktree (lines 188-191 of swarmforge.bb), and Git worktrees themselves are independent checkouts with no cross-directory file sharing.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}