How SwarmForge Orchestrates AI Agents for Software Engineering Tasks

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 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	Validates outbound drafts, enforces a mandatory two-call audit step, and writes handoffs to the sender's outbox
ready_for_next.sh	Consumes inbox entries, notifies the agent that work is available, and returns task descriptions
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, 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

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

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:

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.
• Role prompts in swarmforge/roles/*.prompt and a shared constitution provide behavioral constraints and engineering standards.
• The handoff protocol (swarm_handoff.sh, ready_for_next.sh, done_with_current.sh) enforces a mandatory audit step before work transitions between agents.
• The pack cockpit dashboard (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 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, the agent must call 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 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 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.

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