How SwarmForge.bb Handles the Initial Startup Sequence: Complete Pipeline Breakdown

SwarmForge.bb executes a 21-step deterministic pipeline that validates system dependencies, initializes Git repositories, manages tmux sessions, and launches AI agents through a Clojure-based orchestration script.

SwarmForge.bb serves as the entry-point for the unclebob/swarm-forge multi-agent orchestration system. Understanding the swarmforge.bb startup sequence is essential for debugging deployment issues or extending the framework with custom roles. This script transforms a standard directory into a multi-agent development environment through a rigorous initialization protocol defined in swarmforge/scripts/swarmforge.bb.

Phase 1: Dependency Validation and Context Building

The run-main! function (the default entry point) immediately validates the execution environment. It invokes check-dependency! to verify that tmux, git, and bb (Babashka) binaries exist on the system path (swarmforge.bb#L63-L66).

Once validated, the script constructs a context map using the context function (swarmforge.bb#L59-L70). This map captures critical paths including the working directory, script directory, and generates a unique tmux socket name for session isolation.

The detect-tmux-base-indexes function (swarmforge.bb#L88-L99) then probes any existing tmux server to read base-index and pane-base-index configurations. This ensures that SwarmForge respects the user's existing tmux setup when creating new windows and panes.

Phase 2: Repository Initialization

If the target directory lacks a .git folder, initialize-git-repo! (swarmforge.bb#L22-L28) executes git init, creates a master branch, writes a default .gitignore, and commits the initial state.

The ensure-runtime-git-excludes! function (swarmforge.bb#L16-L21) guarantees that SwarmForge-specific runtime directories remain excluded from the host repository. Following this, install-commit-msg-hook! (swarmforge.bb#L30-L38) writes a Zsh wrapper to .git/hooks/commit-msg that forwards all commit message events to commit_msg_hook.bb for processing.

Phase 3: Configuration Parsing and Backend Detection

The parse-config function (swarmforge.bb#L13-L38) reads swarmforge.conf and constitution.prompt, builds a list of roles (agents), and validates each configuration line. This determines which AI agents (Claude, Codex, Copilot, Grok) will participate in the session.

Simultaneously, detect-terminal-backend (swarmforge.bb#L53-L61) selects the appropriate terminal adapter from iTerm2, Terminal.app, Windows Terminal, or none. The check-backend-dependencies! function (swarmforge.bb#L78-L81) then verifies that each agent binary specified in the configuration is actually installed on the system.

Phase 4: Workspace and Worktree Preparation

The prepare-workspace! function (swarmforge.bb#L12-L19) creates required state directories and generates sessions.tsv and roles.tsv metadata files. It also verifies that helper scripts possess executable permissions.

For multi-agent scenarios, prepare-worktrees! (swarmforge.bb#L21-L27) adds a git worktree for every non-master/non-none worktree defined in the configuration. The prepare-handoff-dirs! function (swarmforge.bb#L31-L35) then creates the .swarmforge/handoffs hierarchy under each worktree to facilitate inter-agent communication.

Phase 5: Session Cleanup and Orchestration

Before launching new agents, the script ensures a clean slate. stop-handoff-daemon! (swarmforge.bb#L71-L75) terminates any existing handoff daemon processes, while kill-existing-sessions! (swarmforge.bb#L26-L30) removes lingering SwarmForge tmux sessions from previous runs.

The boot-sessions! function (swarmforge.bb#L58-L60) creates a dedicated tmux session for each role via create-role-session! and writes the tmux environment file. sync-worktree-scripts! (swarmforge.bb#L55-L71) copies central helper scripts and role-specific prompts into each worktree to ensure agents operate with correct context.

Phase 6: Daemon Launch and Agent Activation

The start-handoff-daemon! function (swarmforge.bb#L98-L106) launches handoffd.bb to monitor the handoff queue, optionally wrapping it in a sleep-inhibitor to prevent system suspension during long-running tasks.

Concurrently, start-pack-web! (swarmforge.bb#L46-L55) executes pack_web.sh to serve the web dashboard, waiting for the dashboard URL file to appear before proceeding.

Finally, launch-roles! (swarmforge.bb#L44-L50) iterates over the role list, optionally sleeping between agent spawns, and invokes launch-role! to build agent-specific commands (Claude, Codex, etc.) and transmit them to their respective tmux panes.

Phase 7: User Interface Handoff

Once all agents are active, announce-ready! (swarmforge.bb#L32-L40) prints a summary of active sessions and the dashboard URL to stdout. The open-terminal-surfaces! function (swarmforge.bb#L66-L72) then either spawns separate terminal windows (when the backend supports window tracking) or falls back to attaching the current shell to the first visible tmux session.

Common Entry Points and CLI Commands

Start a regular project (most common entry point):

bb swarmforge/scripts/swarmforge.bb --start-project /path/to/my/project

Start a host containing multiple packs:

bb swarmforge/scripts/swarmforge.bb /path/to/swarm-forge

Stop a running project cleanly:

bb swarmforge/scripts/swarmforge.bb --stop-project /path/to/my/project

Test configuration parsing without launching agents:

bb swarmforge/scripts/swarmforge.bb --test-parse /path/to/my/project

Debug a specific agent's launch command:

bb swarmforge/scripts/swarmforge.bb --test-launch-command /path/to/project codex "--yolo"

Summary

• SwarmForge.bb validates tmux, git, and bb dependencies before executing any operations.
• The script initializes Git repositories, installs commit hooks, and configures runtime excludes automatically.
• Configuration parsing determines agent roles, while backend detection selects appropriate terminal adapters.
• The system creates isolated git worktrees and tmux sessions for each agent to prevent context contamination.
• A background handoff daemon (handoffd.bb) and web dashboard (pack_web.sh) start before agents receive their launch commands.
• The entry point run-main! coordinates 21 distinct initialization steps to ensure reproducible multi-agent environments across macOS, Linux, and Windows.

Frequently Asked Questions

What happens if SwarmForge.bb detects an existing tmux session?

The kill-existing-sessions! function (swarmforge.bb#L26-L30) automatically terminates any lingering SwarmForge tmux sessions from previous runs before booting new ones. This prevents socket conflicts and stale state, though it means you cannot run multiple independent SwarmForge projects simultaneously using the same tmux server without specifying different socket paths.

How does swarmforge.bb handle missing AI agent binaries?

The check-backend-dependencies! function (swarmforge.bb#L78-L81) validates that each configured agent binary (such as codex, claude, or grok) exists on the system PATH. If a required binary is missing, the script exits with an error before creating any tmux sessions or git worktrees, ensuring the failure happens early in the swarmforge.bb startup sequence rather than mid-execution.

Can swarmforge.bb initialize a Git repository in a non-empty directory?

Yes. The initialize-git-repo! function (swarmforge.bb#L22-L28) runs git init regardless of existing files, creates a master branch, adds a default .gitignore that excludes SwarmForge runtime directories, and performs the initial commit. This allows you to convert existing projects into SwarmForge hosts without manually initializing version control first.

Where does swarmforge.bb store runtime state and handoff files?

The prepare-workspace! function creates state directories and metadata files (sessions.tsv, roles.tsv) in the project root, while prepare-handoff-dirs! (swarmforge.bb#L31-L35) establishes a .swarmforge/handoffs hierarchy under each worktree. These locations are automatically added to .gitignore via ensure-runtime-git-excludes! (swarmforge.bb#L16-L21) to prevent agent communication files from polluting the repository history.

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