How to Set Up SwarmForge for AI Agent Orchestration: A Complete Guide

SwarmForge is a tmux-based orchestration platform that launches AI agents in isolated Git worktrees and coordinates them via a file-based handoff protocol, configurable through a single swarmforge.conf file.

SwarmForge, developed by Uncle Bob Martin in the unclebob/swarm-forge repository, transforms collections of AI agents into disciplined, collaborative software engineers. This open-source framework uses a layered, configuration-driven architecture to manage multi-agent workflows without complex infrastructure. Whether you are running a lightweight two-agent coding session or a comprehensive six-agent pipeline with QA and architecture review, SwarmForge provides the runtime engine to set up SwarmForge for AI agent orchestration in minutes.

What Is SwarmForge?

SwarmForge operates as a tmux-based orchestration platform that treats AI agents as specialized roles working in isolated Git environments. Unlike cloud-based orchestrators, it runs entirely on your local machine using tmux sessions, Bash/Babashka scripts, and file-based communication.

The system follows a branch-pack model where runnable configurations exist in specific branches (e.g., two-pack, four-pack, six-pack), while the main branch contains only shared assets like scripts and constitutional rules. This design allows you to select a pre-configured team topology by simply checking out the appropriate branch.

Core Architecture Components

Understanding the architecture is essential before you configure your first swarm. The platform separates concerns into six distinct layers:

Shared Operational Scripts

Located in swarmforge/scripts/swarmforge.sh and swarmforge/scripts/swarmforge.bb, these Babashka and Bash utilities provide the runtime engine that every role uses. They handle agent launching, tmux session management, and worktree creation. The scripts automatically place the swarmforge/scripts/ directory on each agent's PATH, enabling access to handoff utilities.

Swarm Configuration (swarmforge.conf)

This file drives the shape of your swarm. Each line declares one tmux window with the format:

window <role> <backend> <worktree> [receive-mode] [extra-args]

The first window defined in swarmforge.conf always serves as the cleanup window—closing this window triggers shutdown of the entire tmux server and cleanup of the .swarmforge/ state directory.

Constitution and Articles

The constitution.prompt file and its associated articles in swarmforge/constitution/articles/ (such as engineering.prompt and workflow.prompt) provide shared rules and workflow guidelines. This hierarchy guarantees consistent behavior across all roles and branches, ensuring agents follow the same engineering principles regardless of their specific task.

Role Prompt Files

Individual prompt files in swarmforge/roles/<role>.prompt (e.g., coder.prompt, architect.prompt) tailor each agent's behavior. These map directly to the role entries in swarmforge.conf and define responsibilities, constraints, and communication patterns for specific agent types.

Handoff Protocol

Specified in swarmforge/handoff-protocol.md, this lightweight file-based system queues tasks, notes, or git commits between agents. The daemon handoffd.bb validates, queues, and delivers handoff files to recipient inboxes under .swarmforge/handoffs/, enabling reliable asynchronous communication without direct tmux messaging.

Terminal Adapters

Small scripts in swarmforge/scripts/terminal-adapters/ abstract terminal opening for macOS Terminal, Windows Terminal, Ghostty, and Linux environments. These adapters allow SwarmForge to open dedicated windows per agent or fall back to attaching an existing tmux session if no adapter is available.

Step-by-Step Setup Guide

Follow these steps to set up SwarmForge for AI agent orchestration in your project directory.

1. Choose Your Branch Pack

Select a topology based on project complexity:

• two-pack: coder → cleaner → coder for quick backend work without specifications
• four-pack: specifier → coder → refactorer → architect → specifier for moderate projects requiring Gherkin specs and architectural oversight
• six-pack: specifier → coder → cleaner → architect → hardender → QA → completion for full-featured projects with mutation testing and dedicated QA

2. Download the Runnable Branch

Unlike typical repositories, you download a specific branch rather than main. Replace four-pack with your chosen topology:

BRANCH=four-pack
curl -L "https://github.com/unclebob/swarm-forge/archive/refs/heads/${BRANCH}.tar.gz" | tar -xz --strip-components=1

The main branch contains only shared assets and is not runnable by itself.

3. Initialize the Swarm

From your target project directory, execute the bootstrap script:

./swarm

This wrapper performs several initialization steps defined in the source:

• Copies missing shared scripts from the main branch reference
• Installs constitution articles into swarmforge/constitution/
• Parses swarmforge/swarmforge.conf to determine role topology
• Creates isolated Git worktrees under .worktrees/ for each role (except those mapped to master or none)
• Launches backend processes (e.g., codex, claude, copilot, grok) with their respective role prompts
• Opens terminal surfaces via the adapter contract

4. Verify Worktree Isolation

Check that each agent has its own filesystem view:

ls -la .worktrees/

You should see directories corresponding to each role defined in your swarmforge.conf, such as wt-coder, wt-architect, or wt-specifier. This isolation prevents accidental cross-role file interference while maintaining a shared Git history.

Configuring Your Agents

Editing swarmforge.conf

Modify swarmforge/swarmforge.conf to change backends or add CLI arguments. A typical four-pack configuration looks like:

window specifier codex wt-specifier
window coder codex wt-coder
window refactorer codex wt-refactorer
window architect codex wt-architect

You can substitute codex with claude, copilot, or grok depending on your API access and preferences.

Customizing Role Prompts

To adjust an agent's behavior, edit its prompt file in swarmforge/roles/. For example, modifying swarmforge/roles/coder.prompt changes how the coder interprets tasks and formatting requirements without affecting the architect or specifier roles.

Managing the Handoff Protocol

Once running, agents communicate through the file-based handoff system rather than direct messaging.

Creating a Handoff

From within any agent's worktree (e.g., the coder), draft a handoff file and submit it:

cat > handoff.yaml <<'EOF'
type: git_handoff
to: architect
priority: 10
task: implement-feature-x
commit: abcdef1234
EOF
swarm_handoff.sh handoff.yaml

The swarm_handoff.sh utility validates the YAML and queues it in .swarmforge/handoffs/.

Processing Handoffs

The recipient agent claims the next task using:

ready_for_next.sh

This prints the path to the next handoff file (e.g., TASK: /path/to/handoff.yaml). After completing the work, signal completion:

done_with_current.sh

This updates the queue and notifies the handoffd.bb daemon to deliver the next pending item.

Terminal Behavior and Session Management

SwarmForge uses the terminal adapter contract to open new windows or tabs for each role. If you are using a supported terminal (macOS Terminal, Windows Terminal, Ghostty), each agent appears in its own window. If no adapter matches your environment, SwarmForge attaches to the tmux session directly, and you can switch between windows using standard tmux commands (Ctrl-b n for next window, Ctrl-b p for previous).

To shut down the entire swarm, simply close the first window (the cleanup window). This triggers the shutdown sequence that stops the tmux server, closes all tracked windows, and cleans up the .swarmforge/ state directory.

Summary

• SwarmForge orchestrates AI agents using tmux, Git worktrees, and file-based handoffs, requiring no cloud infrastructure.
• Branch packs (two-pack, four-pack, six-pack) provide pre-configured team topologies; download the specific branch rather than cloning main.
• The ./swarm bootstrap script initializes scripts, constitution articles, worktrees, and terminal windows automatically.
• swarmforge.conf controls the swarm topology, specifying roles, backends (codex, claude, etc.), and worktree mappings.
• Isolated worktrees under .worktrees/ give each agent an independent filesystem view while sharing Git history.
• The handoff protocol (handoff-protocol.md) uses swarm_handoff.sh, ready_for_next.sh, and done_with_current.sh for durable, auditable task queues.

Frequently Asked Questions

What backends does SwarmForge support?

SwarmForge supports pluggable LLM backends including OpenAI Codex, Anthropic Claude, GitHub Copilot, and xAI Grok. You specify the backend per role in swarmforge.conf, allowing mixed environments where, for example, the specifier uses Claude while the coder uses Codex.

Can I run SwarmForge without tmux?

No. SwarmForge is fundamentally a tmux-based orchestration platform. The swarmforge/scripts/swarmforge.bb core logic relies on tmux sessions for process isolation and window management. However, terminal adapters abstract how tmux surfaces are displayed, allowing integration with various terminal emulators.

How do agents communicate without direct messaging?

Agents use a file-based handoff protocol defined in swarmforge/handoff-protocol.md. They write YAML handoff files to a shared queue directory (.swarmforge/handoffs/), which the handoffd.bb daemon validates and routes. This approach guarantees durability and creates an audit trail of all inter-agent communication.

What happens if I close a terminal window accidentally?

Closing any window except the first (cleanup) window only terminates that specific agent. The tmux server continues running, and you can reattach to the session using tmux attach-session -t swarmforge. However, closing the first window defined in swarmforge.conf triggers a full shutdown, stopping all agents and cleaning up state files.

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