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

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:

#!/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 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

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.

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:

# 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
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 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 (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.

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