# SwarmForge Babashka Orchestration Script: The Complete Guide to swarmforge.bb

> Discover swarmforge.bb, the core Babashka orchestration script for Uncle Bob's SwarmForge. Learn how it manages CLI args, dependencies, workspaces, tmux, and LLM agents for seamless agent orchestration.

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

---

**The main Babashka orchestration script for SwarmForge is `swarmforge.bb`, located at `swarmforge/scripts/swarmforge.bb`, which serves as the central entry point that parses CLI arguments, validates dependencies, initializes workspaces, manages tmux sessions, and launches LLM agents.**

The `swarmforge.bb` script acts as the single source of truth for starting a SwarmForge session in the unclebob/swarm-forge repository. Written in Babashka (a native Clojure interpreter), this executable script wires together configuration parsing, terminal multiplexing, and agent orchestration into a seamless workflow for managing multi-agent LLM swarms.

## Core Architecture and Orchestration Flow

The Babashka orchestration script follows a structured pipeline that transforms declarative configuration into running agent processes. According to the SwarmForge source code, the script handles everything from environment validation to terminal window management.

### Entry Point and Namespace Declaration

The script begins with a she-bang declaration that makes it directly executable without explicitly invoking `bb`. The first six lines declare the Babashka environment and import essential helper libraries:

```clojure
#!/usr/bin/env bb

(require '[babashka.fs :as fs])
(require '[babashka.process :as process])
(require '[clojure.string :as str])

```

This setup allows the script to leverage `babashka.fs` for filesystem operations, `babashka.process` for shell command execution, and `clojure.string` for text manipulation throughout the orchestration lifecycle.

### Context Preparation and Configuration

Before spawning agents, the script constructs an execution context that captures paths, configuration, and runtime parameters. The **`context`** function (lines 55–89) builds a map containing critical paths including the working directory, script directory, and tmux socket location. The **`prepare-ctx`** function (lines 90–94) enriches this base context by parsing role configurations from [`swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge.conf) and detecting the appropriate terminal backend.

This context map serves as the immutable state passed between orchestration stages, ensuring that downstream functions have access to normalized paths and validated settings.

### Dependency Validation

Robust orchestration requires verifying the environment before attempting execution. The script implements **`check-dependency!`** and **`check-backend-dependencies!`** (lines 88–95) to ensure required binaries exist in `$PATH`. These functions verify:

- **tmux**: Required for session management and pane isolation
- **git**: Required for worktree operations
- **bb**: The Babashka runtime itself
- **LLM agent binaries**: Specific agents (Claude, Codex, Copilot, Grok) configured in [`swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge.conf)

If any dependency is missing, the script exits with a descriptive error before allocating system resources.

### Workspace and Worktree Initialization

The orchestration script prepares the filesystem hierarchy through three specialized functions (lines 42–65):

- **`prepare-workspace!`**: Creates the hidden `.swarmforge` state directory
- **`prepare-worktrees!`**: Initializes git worktrees for isolated agent workspaces
- **`prepare-handoff-dirs!`**: Sets up hand-off queues for inter-agent communication

These initialization steps ensure that each agent role operates within its own isolated git context while maintaining shared communication channels through the hand-off directory structure.

### Tmux Session Management and Agent Launching

SwarmForge leverages tmux as its process supervision and terminal multiplexing layer. The **`create-role-session!`** function (lines 96–100) creates a dedicated tmux session for each role defined in the configuration, while **`launch-role!`** (lines 151–159) sends the launch command to the appropriate pane.

The **`launch-command`** function (lines 123–143) constructs the final shell command that invokes the selected LLM agent with role-specific prompts and extra arguments. This command builder supports multiple backends including Claude, Codex, GitHub Copilot, and Grok, dynamically adjusting invocation patterns based on the agent type specified in [`swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge.conf).

### Handoff Daemon Integration

To enable agent-to-agent communication, the script manages a background daemon responsible for file-based message passing. The **`start-handoff-daemon!`** function (lines 188–199) spawns `handoffd.bb` (located at `swarmforge/scripts/handoffd.bb`) with optional OS-sleep inhibition to prevent the host from suspending during long-running swarm operations.

This daemon monitors hand-off directories and facilitates the transfer of context and tasks between agents as they complete their assigned roles.

## How to Run the Babashka Orchestration Script

The `swarmforge.bb` script is designed for direct execution via its she-bang line or explicit invocation through Babashka:

```bash

# Make the script executable (one-time setup)

chmod +x swarmforge/scripts/swarmforge.bb

# Run SwarmForge in the current directory (defaults to $PWD)

./swarmforge/scripts/swarmforge.bb

# Explicitly specify a different project root

bb swarmforge/scripts/swarmforge.bb /path/to/your/project

```

When executed, the script performs the following sequence:
1. Validates that `tmux`, `git`, and configured LLM binaries are installed
2. Initializes the `.swarmforge` state directory in the target project
3. Creates isolated tmux sessions for each role defined in [`swarmforge/swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/swarmforge.conf)
4. Starts the hand-off daemon (`handoffd.bb`) for inter-agent communication
5. Launches each agent in its designated tmux pane with role-specific prompts
6. Optionally opens separate terminal windows if a supported backend (iTerm, Windows Terminal) is detected

## Key Implementation Details

The **`-main`** function (lines 179–191) serves as the primary entry point, parsing sub-commands such as `--test-parse` and `--test-launch-command` for debugging purposes. By default, it delegates to **`run-main!`**, which orchestrates the complete startup sequence.

Terminal backend integration (lines 210–260) includes adapter scripts for platform-specific terminal emulators. The **`open-terminal-surfaces!`** and **`adapter-script`** functions detect the host environment and generate appropriate commands to spawn visible terminal windows alongside the headless tmux sessions.

## Summary

- **The main Babashka orchestration script for SwarmForge is `swarmforge/scripts/swarmforge.bb`**, containing the `-main` entry point that coordinates the entire system.
- **Context preparation** involves the `context` and `prepare-ctx` functions building a comprehensive configuration map from [`swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge.conf) and environment detection.
- **Dependency validation** through `check-dependency!` ensures `tmux`, `git`, `bb`, and LLM agents are available before execution.
- **Workspace initialization** creates isolated git worktrees and hand-off directories for multi-agent coordination.
- **Tmux integration** provides process isolation, with `create-role-session!` and `launch-role!` managing agent lifecycles.
- **Handoff daemon management** via `start-handoff-daemon!` enables asynchronous communication between agents using `handoffd.bb`.

## Frequently Asked Questions

### What is the main Babashka orchestration script in SwarmForge?

The main Babashka orchestration script is `swarmforge.bb`, located at `swarmforge/scripts/swarmforge.bb` in the unclebob/swarm-forge repository. This script contains the `-main` function and serves as the executable entry point that coordinates dependency checks, workspace initialization, tmux session creation, and agent launching for the entire SwarmForge system.

### How does swarmforge.bb manage tmux sessions?

The script uses `create-role-session!` (lines 96–100) to create isolated tmux sessions for each role defined in the configuration, and `launch-role!` (lines 151–159) to dispatch commands to specific panes. This architecture ensures that each LLM agent operates in its own isolated terminal environment while remaining manageable through a unified tmux socket.

### What dependencies does the SwarmForge orchestration script check?

The script validates the presence of `tmux` for terminal multiplexing, `git` for repository operations, `bb` (Babashka itself) for script execution, and the specific LLM agent binaries configured in [`swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge.conf) (such as Claude, Codex, Copilot, or Grok). These checks occur in `check-dependency!` and `check-backend-dependencies!` before any orchestration begins.

### How does the script handle different LLM agents?

The `launch-command` function (lines 123–143) dynamically constructs shell commands based on the agent type specified in the role configuration. It supports multiple LLM backends including Claude, Codex, GitHub Copilot, and Grok, injecting the appropriate prompt files from `swarmforge/roles/*.prompt` and passing any extra arguments required by the specific agent binary.