How SwarmForge Creates and Manages Git Worktrees for Each Role

SwarmForge uses a deterministic, configuration-driven startup sequence that reads 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. 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 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 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:

# 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:

# 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:

# 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 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 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 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 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.

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