# How Git Worktrees Enable Agent Isolation in SwarmForge > Discover how SwarmForge uses Git worktrees for agent isolation. Each role gets a separate working directory sharing Git history, preventing conflicts and maintaining a single source of truth. - Repository: [Robert C. Martin/swarm-forge](https://github.com/unclebob/swarm-forge) - Tags: how-to-guide - Published: 2026-08-31 --- **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: ```clojure (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 worktree add --force -B swarmforge- HEAD` establishes the isolated checkout. ## Role Configuration in swarmforge.conf Agent-to-worktree mappings reside in [`swarmforge/swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/swarmforge.conf). Each line declares a window, role name, backend, and worktree designation: ```conf 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: ```clojure {: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`](https://github.com/unclebob/swarm-forge/blob/main/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.