# How SwarmForge Creates and Manages Git Worktrees for Each Role

> Learn how SwarmForge creates and manages Git worktrees for each role using its configuration-driven startup for concurrent AI agent development without conflicts.

- Repository: [Robert C. Martin/swarm-forge](https://github.com/unclebob/swarm-forge)
- Tags: how-to-guide
- Published: 2026-08-08

---

**SwarmForge uses a deterministic, configuration-driven startup sequence that reads [`swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge.conf) to create isolated Git worktrees under `.worktrees/` for every role, enabling concurrent AI agent development without merge conflicts.**

The `unclebob/swarm-forge` repository implements a sophisticated multi-agent orchestration system where each AI role operates in its own isolated Git environment. By creating and managing git worktrees for each role in SwarmForge, the platform ensures that multiple agents can simultaneously modify code without interfering with each other's working directories. This architecture leverages Git's native worktree feature to provide true filesystem isolation while maintaining a shared repository history.

## Configuration-Driven Worktree Initialization

The process begins when the `./swarm` launcher reads the topology definition from [`swarmforge/swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/swarmforge.conf). Each line in this configuration file defines a window (role) and specifies the worktree name that role will use. For example, entries like `window coder codex coder` instruct the system to create a dedicated worktree named `coder` for the coder role.

## The Seven-Step Worktree Creation Process

SwarmForge executes a precise startup sequence in [`swarmforge/scripts/swarmforge.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/swarmforge.sh) to establish the isolated environments.

### Step 1: Repository Initialization

If the target directory is not yet a Git repository, SwarmForge automatically runs `git init` and creates an initial commit. This ensures the repository is ready for worktree operations before proceeding with role-specific setup.

### Step 2: Creating Isolated Worktrees

For every role whose worktree name is **not** `master` or `none`, SwarmForge executes `git worktree add` to create a fresh checkout under the hidden directory `.worktrees/`. The worktree path follows the pattern `.worktrees/${WORKTREE_NAME}`, such as `.worktrees/coder` or `.worktrees/architect`. When the configuration specifies `master`, the role operates directly in the main checkout without creating an additional directory.

### Step 3: Synchronizing Shared Resources

After creating the worktree, SwarmForge copies shared helper scripts from `swarmforge/scripts/` and any missing constitution articles into each role's directory. Existing local files remain untouched, allowing individual worktrees to override shared articles when necessary. This synchronization ensures all agents have access to common utilities while preserving the ability to customize their environment.

### Step 4: Configuring the Environment PATH

The script directory inside each worktree (`swarmforge/scripts/`) is prepended to the agent's `$PATH` environment variable. This configuration ensures that agents invoke local helper scripts like [`swarm_handoff.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarm_handoff.sh) from their own worktree rather than reaching back into the main checkout, maintaining complete isolation between roles.

### Step 5: Launching the Agent Session

With the worktree fully prepared, SwarmForge opens a tmux session (or OS-specific terminal window) pointing to the worktree's root directory. The backend for the role—such as `codex` or `claude`—starts inside this session, giving the agent a dedicated filesystem view isolated from other roles.

### Step 6: Managing Runtime Handoffs

All inter-agent communication files live under `.swarmforge/handoffs/` inside each worktree. The `handoffd.bb` daemon watches each worktree's outbox directory, moves validated handoffs to appropriate inboxes, and notifies target agents. Because handoff state is scoped to the worktree, agents interact only with their local filesystem, never touching the main repository directly.

## Practical Configuration Examples

The following examples demonstrate how to configure and extend worktree setups in SwarmForge.

**Minimal configuration triggering worktree creation:**

```conf

# swarmforge/swarmforge.conf

window coordinator codex master          # runs in the main checkout

window coder       codex coder           # creates .worktrees/coder

window refactorer  codex refactorer      # creates .worktrees/refactorer

window architect   codex architect        # creates .worktrees/architect

```

**Internal worktree creation command:**

```bash

# Executed by swarmforge/scripts/swarmforge.sh for each non-master role

git worktree add ".worktrees/${WORKTREE_NAME}" "${BRANCH}"

# Where WORKTREE_NAME is the role identifier and BRANCH is the target branch

```

**Adding a new role programmatically:**

```bash

# Append new role to configuration

echo "window tester codex tester" >> swarmforge/swarmforge.conf

# Re-run the launcher to auto-provision the worktree

./swarm

```

## Summary

- SwarmForge reads role definitions from [`swarmforge/swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/swarmforge.conf) to determine worktree allocation.
- Each role receives an isolated Git worktree under `.worktrees/${ROLE_NAME}`, except for roles designated as `master`.
- The startup script [`swarmforge/scripts/swarmforge.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/swarmforge.sh) handles repository initialization, worktree creation, and resource synchronization.
- Shared scripts and articles are copied into each worktree, with local overrides taking precedence.
- Agent sessions launch inside tmux windows rooted in their respective worktrees, ensuring filesystem isolation.
- Runtime handoffs operate within `.swarmforge/handoffs/` inside each worktree, managed by the `handoffd.bb` daemon.

## Frequently Asked Questions

### What is the difference between "master" and "none" worktree names in the configuration?

When [`swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge.conf) specifies `master` as the worktree name, the role operates directly in the main repository checkout without creating a separate directory. If `none` is specified, SwarmForge skips worktree creation entirely for that role, which may be used for coordinator roles that don't need filesystem isolation or direct code access.

### Where are handoff files stored within each worktree?

Handoff files reside in `.swarmforge/handoffs/` inside each role's worktree directory. The daemon monitors the `outbox` subdirectory within this path and moves validated messages to target inboxes, ensuring all inter-agent communication remains scoped to the isolated worktree environment.

### Can multiple roles share the same physical worktree?

No. SwarmForge creates distinct worktrees for each non-master role to prevent file conflicts. While roles share the same Git history, their working directories are completely isolated. This design prevents concurrent agents from overwriting each other's uncommitted changes or temporary files.

### How do I add a new role to an existing SwarmForge deployment?

Append the new role definition to [`swarmforge/swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/swarmforge.conf) using the format `window <role_name> <backend> <worktree_name>`, then re-run the `./swarm` launcher. The startup sequence automatically detects the new entry, creates the corresponding worktree under `.worktrees/`, synchronizes shared resources, and launches the new agent session without disturbing existing roles.