# How SwarmForge.bb Handles the Initial Startup Sequence: Complete Pipeline Breakdown > Discover how SwarmForge.bb executes its 21-step startup pipeline, from dependency validation and Git initialization to tmux sessions and AI agent launches via Clojure. - Repository: [Robert C. Martin/swarm-forge](https://github.com/unclebob/swarm-forge) - Tags: internals - Published: 2026-08-31 --- **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`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/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): ```bash bb swarmforge/scripts/swarmforge.bb --start-project /path/to/my/project ``` Start a host containing multiple packs: ```bash bb swarmforge/scripts/swarmforge.bb /path/to/swarm-forge ``` Stop a running project cleanly: ```bash bb swarmforge/scripts/swarmforge.bb --stop-project /path/to/my/project ``` Test configuration parsing without launching agents: ```bash bb swarmforge/scripts/swarmforge.bb --test-parse /path/to/my/project ``` Debug a specific agent's launch command: ```bash 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`](https://github.com/unclebob/swarm-forge/blob/main/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.