# SwarmForge Script and Configuration Files: The Complete Architecture Guide > Explore the SwarmForge architecture, detailing essential scripts and configuration files like swarmforge.conf. Understand how Bash/Babashka scripts orchestrate AI agent swarms. - Repository: [Robert C. Martin/swarm-forge](https://github.com/unclebob/swarm-forge) - Tags: architecture - Published: 2026-08-09 --- **SwarmForge orchestrates AI-agent swarms through a lightweight combination of Bash/Babashka scripts located in `swarmforge/scripts/` and declarative configuration files like [`swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge.conf), creating git work-trees for isolated agent contexts, and spawning tmux sessions for each defined role. ```bash # 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`](https://github.com/unclebob/swarm-forge/blob/main/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. ```bash # 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`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/ready_for_next.sh) script polls an agent's inbox for pending tasks, returning either `NO_TASK` or `TASK: ` to signal available work. Conversely, [`swarmforge/scripts/done_with_current.sh`](https://github.com/unclebob/swarm-forge/blob/main/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. ```bash # Accept the next task (or batch) in a role's inbox ready_for_next.sh # Prints either "NO_TASK" or "TASK: ", causing the agent to load the payload. ``` ```bash # 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`](https://github.com/unclebob/swarm-forge/blob/main/ghostty.sh), [`windows-terminal.sh`](https://github.com/unclebob/swarm-forge/blob/main/windows-terminal.sh), [`terminal-app.sh`](https://github.com/unclebob/swarm-forge/blob/main/terminal-app.sh) (macOS), and [`none.sh`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/swarmforge.conf) declares every window in the swarm using the format: ` [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`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge.conf) requires a corresponding prompt file in `swarmforge/roles/.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`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/ready_for_next.sh) to poll for tasks and [`swarm_handoff.sh`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/swarm-cleanup.sh) for graceful shutdown. ## Summary - **Entry points**: [`swarmforge.sh`](https://github.com/unclebob/swarm-forge/blob/main/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`](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), and [`swarm_handoff.sh`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/ghostty.sh) or [`windows-terminal.sh`](https://github.com/unclebob/swarm-forge/blob/main/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/.prompt` files. Each role listed in [`swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge.conf) must have a corresponding prompt file to define its specialized behavior and constraints.