How to Install SwarmForge: Complete Setup Guide for AI‑Agent Orchestration

SwarmForge installation requires installing prerequisites (zsh, git, tmux, Babashka, and an LLM backend), copying the get-swarm-forge helper to your PATH, running it once in your chosen forge directory, and launching the dashboard with ./swarm.

SwarmForge is a tmux‑based orchestration platform for running AI‑agent swarms, developed by Uncle Bob (Robert C. Martin) in the unclebob/swarm-forge repository. This guide walks through the complete installation process using the actual source files and scripts from the project.

Prerequisites for Running SwarmForge

Before installing SwarmForge, ensure your machine has the following tools available:

• zsh — the Z shell environment
• git — for cloning branches and managing packs
• tmux — terminal multiplexer for session management
• Babashka (bb) — native Clojure scripting engine that powers the runtime
• At least one LLM backend — codex, claude, copilot, or grok

These requirements are documented in README.md at lines 71–78 of the source repository.

Install the get-swarm-forge Helper Script

The get-swarm-forge script is the bootstrap installer for the entire platform. It handles downloading all branches, setting up the directory structure, and preparing the forge workspace.

Step 1: Copy the Helper to Your PATH

Choose a directory on your shell PATH (commonly ~/cmds or ~/bin):

mkdir -p ~/cmds
cp get-swarm-forge ~/cmds/get-swarm-forge
chmod +x ~/cmds/get-swarm-forge

This snippet comes directly from the installation section in README.md (lines 83–89).

Step 2: Run the Installer in Your Forge Directory

Navigate to any empty directory you want to become your forge — the root workspace that will hold all packs and projects:

cd ~/my-swarm-forge
get-swarm-forge

Running get-swarm-forge once performs the following actions (as implemented in the get-swarm-forge script):

• Downloads the main branch and every pack branch (two-pack, four-pack, six-pack)
• Copies host scripts from swarmforge/scripts/ into a top‑level swarmforge/ directory
• Places each pack's template under packs/<pack-name>/
• Creates an empty projects/ folder ready for new projects

No further network access is required after this initial run.

Start the SwarmForge Dashboard

From the forge root directory, launch the orchestration system:

./swarm

The swarm wrapper script executes swarmforge/scripts/swarmforge.sh to:

• Start the lieutenant agent
• Launch the local web dashboard
• Initialize the tmux session for hosting project agents

The dashboard prints a URL (also written to .swarmforge/dashboard-url) and automatically opens it in your browser if the open command is available. See README.md lines 101–107 for the official launch instructions.

Create Your First Project

Once the dashboard is running:

1. Click New Project
2. Enter a project name
3. Select a pack: two-pack, four-pack, or six-pack
4. Optionally specify a GitHub repository
5. Confirm to create

The UI generates projects/<name>/ containing:

• A mission.md file for project context
• A copy of the selected pack's configuration
• Automatically started agents for the chosen pack topology

Optional Environment Configuration

Control SwarmForge behavior with these environment variables:

Variable	Purpose	Default
SWARMFORGE_OPEN_BROWSER	Set to 0 to suppress automatic browser launch	1
SWARMFORGE_PREVENT_SLEEP	Set to 0 to disable the OS sleep inhibitor	1

Example:

SWARMFORGE_OPEN_BROWSER=0 ./swarm

Complete Installation Example

# Install the helper script

mkdir -p ~/cmds
cp get-swarm-forge ~/cmds/get-swarm-forge
chmod +x ~/cmds/get-swarm-forge

# Create and populate your forge

mkdir -p ~/swarm-forge
cd ~/swarm-forge
get-swarm-forge

# Launch the platform

./swarm

# → Dashboard URL printed and opened in browser

# (In browser) Create project "demo" with two-pack topology

# → New Project → Name: demo → Pack: two-pack → Create

Key Files in the SwarmForge Installation

Understanding these files helps troubleshoot and extend your installation:

File	Location	Purpose
README.md	Repository root	Official documentation and prerequisites
get-swarm-forge	Repository root	Bootstrap installer that downloads branches and creates the forge structure
swarm	Forge root after install	Launcher wrapper that starts the dashboard
swarmforge/scripts/swarmforge.sh	swarmforge/scripts/	Core runtime that boots tmux sessions and orchestrates agents
swarmforge/conf/swarmforge.conf	Inside each pack	Defines window/role topology for that pack
swarmforge/constitution/articles/*.prompt	swarmforge/constitution/	Shared engineering rules inherited by all packs
packs/<pack>/swarmforge/roles/*.prompt	Per-pack	Role‑specific prompts for each LLM backend
projects/<name>/	Generated at runtime	Project workspace with mission.md and local configuration

Summary

SwarmForge installation follows a clear three‑phase pattern:

• Prepare prerequisites: zsh, git, tmux, Babashka, and an LLM backend
• Bootstrap with get-swarm-forge: Copy the helper to PATH, run once in your chosen directory to download all branches and create the forge structure
• Launch with ./swarm: Start the dashboard, create projects through the web UI, and begin orchestrating agent swarms

The entire process is self‑contained after the initial download, with all runtime logic living in swarmforge/scripts/swarmforge.sh and configuration managed through pack templates and project workspaces.

Frequently Asked Questions

What is the minimum system requirement for SwarmForge?

You need a Unix‑like system with zsh, git, tmux, and Babashka installed, plus at least one supported LLM backend (codex, claude, copilot, or grok). No Docker or container runtime is required. The platform runs entirely through shell scripts and tmux sessions.

Can I install SwarmForge without cloning the entire repository first?

Yes. Copy only the get-swarm-forge script from the unclebob/swarm-forge repository, place it on your PATH, and run it. This script downloads the main branch and all pack branches automatically. You do not need a prior git clone of the repository.

Where does SwarmForge store project data?

All project data lives in the projects/ directory under your forge root, created by get-swarm-forge during installation. Each project gets its own subdirectory containing mission.md, a local swarmforge.conf, and generated worktrees. The dashboard URL is cached in .swarmforge/dashboard-url at the forge root.

How do I switch between different agent pack sizes?

During project creation in the dashboard, select from two-pack, four-pack, or six-pack. Each pack template resides in packs/<pack-name>/ with its own swarmforge/conf/swarmforge.conf defining the window and role topology. You cannot change a project's pack after creation; create a new project with the desired pack instead.

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