# How SwarmForge Orchestrates AI Agents for Software Engineering Tasks

> Discover how SwarmForge orchestrates AI agents using role isolation and git worktrees for collaborative software engineering. Streamline your development workflow.

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

---

**SwarmForge is a tmux-based orchestration platform that coordinates multiple AI agents through role-based isolation, git worktrees, and a validated handoff protocol to perform collaborative software engineering.**

SwarmForge transforms a swarm of large language models into a disciplined development team by assigning each agent a specific role, isolating their execution environments, and enforcing a structured communication protocol. According to the `unclebob/swarm-forge` source code, the system uses configuration-driven templates (called "packs") rather than hard-coded logic, allowing teams to instantiate two-agent, four-agent, or six-agent swarms with a single command.

## Role-Based Topology and Configuration

The foundation of SwarmForge orchestration lies in declarative configuration files that define the swarm's shape and behavior.

**Swarm Configuration**  
The file [`swarmforge/swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/swarmforge.conf) enumerates the active roles in a pack (e.g., `specifier`, `coder`, `cleaner`, `architect`) and specifies backend LLM providers such as `claude`, `codex`, `copilot`, or `grok`. The launcher validates these roles against their corresponding prompt files before initializing the environment.

**Constitution and Role Prompts**  
Each role receives a dedicated prompt file located at `swarmforge/roles/<role>.prompt` that defines its responsibilities and tool access. All agents inherit a shared "constitution" from `swarmforge/constitution.prompt` and `swarmforge/constitution/articles/*.prompt`, which contains engineering rules, workflow policies, and handoff guidelines. This layered approach ensures consistent behavior while allowing role-specific specialization.

## Isolation and Execution Model

SwarmForge achieves process isolation by combining terminal multiplexing with git worktrees.

**tmux Session Management**  
The starter script `swarmforge/scripts/swarmforge.bb` creates a tmux session named after the project and spawns one pane per defined role. Each pane runs its agent's backend in isolation, preventing file system collisions while maintaining shared access to helper scripts in `swarmforge/scripts/`.

**Git Worktree Isolation**  
For every role except `master` or `none`, the launcher creates a dedicated git worktree under `.worktrees/<role>/`. This architecture allows agents to work on different branches or commits simultaneously without interfering with each other's working directories, while the `handoffd.bb` daemon coordinates cross-worktree communication.

## The Handoff Protocol

The communication backbone of SwarmForge is a validated handoff protocol that ensures work passes between agents only after audit requirements are met.

| Script | Function |
|--------|----------|
| [`swarm_handoff.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarm_handoff.sh) | Validates outbound drafts, enforces a mandatory two-call audit step, and writes handoffs to the sender's outbox |
| [`ready_for_next.sh`](https://github.com/unclebob/swarm-forge/blob/main/ready_for_next.sh) | Consumes inbox entries, notifies the agent that work is available, and returns task descriptions |
| [`done_with_current.sh`](https://github.com/unclebob/swarm-forge/blob/main/done_with_current.sh) | Marks tasks complete, queues pending mail, and optionally triggers the next `ready_for_next` call |

**Handoff File Structure**  
Handoffs reside in `.swarmforge/handoffs/` within each worktree, organized into `outbox`, `inbox`, `sent`, and `failed` directories. When an agent drafts a handoff, it executes `swarm_handoff.sh <draft_file>`. The first valid call returns `AUDIT_REQUIRED`, forcing the agent to review its work. Upon a second unchanged call, the `handoffd.bb` daemon delivers the file to the recipient's inbox and sends a wake-up notification to their tmux pane.

## Human Oversight with the Pack Cockpit

SwarmForge includes a local web dashboard called the **pack cockpit** that provides visibility and control over the agent swarm.

**Dashboard Features**  
Running via [`swarmforge/scripts/pack_web.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/pack_web.sh), the dashboard displays project swimlanes, an attention list for human approvals, a kanban-style board with task cards that move automatically as handoffs complete, and a chat interface with the **lieutenant**—a global overseer LLM (defaulting to `grok`) that mediates high-level coordination.

**Task Lifecycle**  
Humans create tasks through the dashboard UI, which generates cards and queues `New Task` notes to the `master` role. As agents process work and execute the handoff protocol, the dashboard updates card positions in real-time, creating a transparent view of the software engineering pipeline.

## Practical Workflow Example

Below is a minimal end-to-end workflow demonstrating how SwarmForge orchestrates a task from initiation to completion.

**1. Initialize the Swarm**

```bash

# Install the helper utility

cp get-swarm-forge ~/bin/
get-swarm-forge  # Clones packs, creates projects/, installs scripts

# Launch the dashboard and lieutenant

./swarm  # Outputs: http://127.0.0.1:8000

```

**2. Draft and Send a Handoff**

From within a role's worktree (e.g., `.worktrees/coder`):

```bash
cat > ./tmp/handoff.txt <<'EOF'
type: git_handoff
to: cleaner
priority: 10
task: add-validation-module
commit: a1b2c3d4e5
EOF

# First call triggers audit requirement

swarm_handoff.sh ./tmp/handoff.txt   # => AUDIT_REQUIRED

# After internal review, second unchanged call queues the handoff

swarm_handoff.sh ./tmp/handoff.txt   # => queued

```

**3. Receive and Process Work**

In the recipient's tmux pane:

```bash
ready_for_next.sh

# Output: TASK: .worktrees/cleaner/inbox/git_handoff-1234.txt

# Agent checks out the commit, performs its role, then signals completion

done_with_current.sh  # Returns MAIL_WAITING if more tasks exist

```

## Summary

- **SwarmForge** orchestrates AI agents using a **tmux-based** architecture with **git worktree isolation** defined in [`swarmforge/swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/swarmforge.conf).
- **Role prompts** in `swarmforge/roles/*.prompt` and a shared **constitution** provide behavioral constraints and engineering standards.
- The **handoff protocol** ([`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), [`done_with_current.sh`](https://github.com/unclebob/swarm-forge/blob/main/done_with_current.sh)) enforces a mandatory **audit step** before work transitions between agents.
- The **pack cockpit** dashboard ([`pack_web.sh`](https://github.com/unclebob/swarm-forge/blob/main/pack_web.sh)) provides real-time visibility and human oversight through a lieutenant LLM.
- Configuration-driven **pack templates** (`two-pack`, `four-pack`, `six-pack`) allow instantiation of different swarm topologies via `get-swarm-forge`.

## Frequently Asked Questions

### How does SwarmForge prevent AI agents from interfering with each other's work?

Each agent operates inside a dedicated **git worktree** under `.worktrees/<role>/` and a separate **tmux pane**, ensuring file system isolation. The handoff protocol in [`swarmforge/scripts/swarm_handoff.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/swarm_handoff.sh) validates all cross-agent communication before delivery, preventing unauthorized direct access between worktrees.

### What is the purpose of the AUDIT_REQUIRED response in the handoff protocol?

The `AUDIT_REQUIRED` response forces an agent to perform a self-review before completing a handoff. According to [`swarmforge/handoff-protocol.md`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/handoff-protocol.md), the agent must call [`swarm_handoff.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarm_handoff.sh) a second time with an unchanged draft to confirm the audit occurred, ensuring quality control before the `handoffd.bb` daemon delivers the work to the next role's inbox.

### Can SwarmForge integrate with different LLM providers?

Yes. The [`swarmforge/swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/swarmforge.conf) file specifies backend providers per role, supporting `claude`, `codex`, `copilot`, `grok`, and others. Each role's prompt file in `swarmforge/roles/*.prompt` can configure provider-specific instructions while inheriting shared rules from the constitution files.

### How does a human operator monitor the swarm's progress?

The **pack cockpit** dashboard launched via [`swarmforge/scripts/pack_web.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/pack_web.sh) renders a local web interface showing project swimlanes, automatic card movements on the task board, and an attention list requiring human approval. The lieutenant LLM facilitates chat-based interaction for high-level coordination and task creation.