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

> Learn how to set up SwarmForge, a tmux-based platform for AI agent orchestration. This guide covers configuration and launching agents with ease.

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

---

**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`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge.conf))

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

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

```

The first window defined in [`swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge.conf) and define responsibilities, constraints, and communication patterns for specific agent types.

### Handoff Protocol

Specified in [`swarmforge/handoff-protocol.md`](https://github.com/unclebob/swarm-forge/blob/main/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:

```bash
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:

```bash
./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`](https://github.com/unclebob/swarm-forge/blob/main/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:

```bash
ls -la .worktrees/

```

You should see directories corresponding to each role defined in your [`swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge.conf)

Modify [`swarmforge/swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/swarmforge.conf) to change backends or add CLI arguments. A typical four-pack configuration looks like:

```conf
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:

```bash
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`](https://github.com/unclebob/swarm-forge/blob/main/swarm_handoff.sh) utility validates the YAML and queues it in `.swarmforge/handoffs/`.

### Processing Handoffs

The recipient agent claims the next task using:

```bash
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:

```bash
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`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/handoff-protocol.md)) uses [`swarm_handoff.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarm_handoff.sh), [`ready_for_next.sh`](https://github.com/unclebob/swarm-forge/blob/main/ready_for_next.sh), and [`done_with_current.sh`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge.conf) triggers a full shutdown, stopping all agents and cleaning up state files.