SwarmForge Script and Configuration Files: The Complete Architecture Guide

SwarmForge orchestrates AI-agent swarms through a lightweight combination of Bash/Babashka scripts located in swarmforge/scripts/ and declarative configuration files like swarmforge.conf and role-specific prompts.

The unclebob/swarm-forge repository implements a tmux-based orchestration layer that enables multiple AI agents to collaborate on complex engineering tasks. Understanding the key SwarmForge script and configuration files is essential for customizing swarm behavior, debugging handoff protocols, and extending the framework to new terminal environments.

Core Orchestration Scripts

swarmforge.sh and swarmforge.bb

The primary entry points for any swarm deployment are swarmforge/scripts/swarmforge.sh (Bash) and swarmforge/scripts/swarmforge.bb (Babashka). These scripts handle the initialization sequence: copying shared scripts into the runtime environment, validating the configuration against swarmforge.conf, creating git work-trees for isolated agent contexts, and spawning tmux sessions for each defined role.

# Start a swarm from a runnable branch (e.g., four-pack)

BRANCH=four-pack
curl -L "https://github.com/unclebob/swarm-forge/archive/refs/heads/${BRANCH}.tar.gz" |
  tar -xz --strip-components=1
./swarm                       # launches the swarm using the config in swarmforge/swarmforge.conf

handoffd.bb and handoff_lib.bb

The swarmforge/scripts/handoffd.bb daemon owns the tmux socket and manages the inter-agent messaging backbone. It monitors each agent's outbox directory (.swarmforge/handoffs/outbox/), validates incoming handoff files, delivers them to the appropriate inboxes, and sends wake-up notifications to idle agents. The companion handoff_lib.bb provides shared validation logic for handoff schema compliance.

Agent Communication Utilities

swarm_handoff.sh

Agents invoke swarmforge/scripts/swarm_handoff.sh (or its swarm_handoff.bb equivalent) to submit completed work. This utility validates the draft handoff YAML, ensures commit abbreviations are correct, and queues the payload for delivery by the daemon.

# Submit a git-based handoff from an agent

swarm_handoff.sh my-draft.yaml

# The script validates the commit abbreviation, creates a handoff payload,

# and places it in .swarmforge/handoffs/outbox/

ready_for_next.sh and done_with_current.sh

The swarmforge/scripts/ready_for_next.sh script polls an agent's inbox for pending tasks, returning either NO_TASK or TASK: <path> to signal available work. Conversely, swarmforge/scripts/done_with_current.sh marks the active task as complete, removes the processed handoff file, and triggers the watchdog to fetch subsequent items.

# Accept the next task (or batch) in a role's inbox

ready_for_next.sh

# Prints either "NO_TASK" or "TASK: <path>", causing the agent to load the payload.

# Mark the current work as complete

done_with_current.sh

# Removes the processed handoff and triggers the watchdog to fetch the next one.

Terminal Management Layer

Terminal Adapters

SwarmForge abstracts terminal detection through adapter scripts located in swarmforge/scripts/terminal-adapters/. Concrete implementations include ghostty.sh, windows-terminal.sh, terminal-app.sh (macOS), and none.sh. These scripts define how new tmux sessions are exposed to the user interface based on the host environment.

swarm-terminal-adapter.sh

The dispatcher script swarmforge/scripts/swarm-terminal-adapter.sh reads the SWARMFORGE_TERMINAL environment variable to select the appropriate adapter implementation, proxying window creation calls to the underlying terminal-specific logic.

swarm-window-watchdog.sh

To ensure operational resilience, swarmforge/scripts/swarm-window-watchdog.sh monitors terminal windows opened by adapters. If a window disappears unexpectedly, the watchdog respawns it, maintaining the swarm's interactive surface.

swarm-cleanup.sh

When the first (cleanup) window closes, swarmforge/scripts/swarm-cleanup.sh executes to shut down tmux sessions, terminate the watchdog process, and restore the original environment state.

Configuration and Prompt System

swarmforge.conf

The central configuration file swarmforge/swarmforge.conf declares every window in the swarm using the format: <role> <backend> <worktree> [task|batch] [extra-cli-args…]. This file drives work-tree creation, tmux session initialization, and backend selection for each agent.

Constitution and Articles

The swarmforge/constitution.prompt file serves as the top-level system prompt entry point, instructing agents to read shared articles located in swarmforge/constitution/articles/. Key articles include engineering.prompt (coding standards), handoffs.prompt (inter-agent protocol), and workflow.prompt (operational expectations).

Role-Specific Prompts

Each role defined in swarmforge.conf requires a corresponding prompt file in swarmforge/roles/<role>.prompt (e.g., coder.prompt, architect.prompt). These files provide specialized system instructions that shape agent behavior for specific responsibilities.

Operational Workflow

When initializing a swarm, the launcher reads swarmforge.conf and creates isolated git work-trees for each role. The handoffd.bb daemon starts first, establishing the communication backbone. Each agent then executes within its tmux window, using ready_for_next.sh to poll for tasks and swarm_handoff.sh to submit results. The terminal adapter opens visible surfaces for human oversight, while the watchdog ensures continuity. Closing the first window triggers swarm-cleanup.sh for graceful shutdown.

Summary

• Entry points: swarmforge.sh and swarmforge.bb initialize the entire orchestration environment and git work-trees.
• Communication backbone: handoffd.bb manages validated handoffs between agents via inbox/outbox directories.
• Task lifecycle: ready_for_next.sh, done_with_current.sh, and swarm_handoff.sh implement the agent-side handoff protocol.
• Terminal abstraction: Adapter scripts in terminal-adapters/ and the watchdog ensure persistent interactive windows across platforms.
• Configuration hierarchy: swarmforge.conf defines topology, while constitution.prompt and role files define agent behavior.

Frequently Asked Questions

What is the difference between swarmforge.sh and swarmforge.bb?

Both files implement identical initialization logic, but swarmforge.sh runs in standard Bash while swarmforge.bb executes under Babashka (Clojure on the JVM). Users choose based on their runtime environment preferences and dependency availability.

How does handoffd.bb validate handoff files?

The daemon validates commit abbreviations, ensures YAML schema compliance, and verifies destination inbox existence before moving files from .swarmforge/handoffs/outbox/ to the target role's inbox directory.

Can I add custom terminal adapters?

Yes. Create a new script in swarmforge/scripts/terminal-adapters/ following the interface established by ghostty.sh or windows-terminal.sh, then set SWARMFORGE_TERMINAL to match your adapter's basename.

Where are role-specific system prompts stored?

Role prompts reside in swarmforge/roles/<role>.prompt files. Each role listed in swarmforge.conf must have a corresponding prompt file to define its specialized behavior and constraints.

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