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

Install SwarmForge in three steps: install prerequisites (zsh, git, tmux, bb/babashka, and an LLM backend), run the get-swarm-forge helper in your chosen workspace directory, then launch the dashboard with ./swarm.

SwarmForge is a tmux-based orchestration platform for AI-agent swarms developed by Robert C. Martin (Uncle Bob). This guide walks through the complete SwarmForge installation process using the official unclebob/swarm-forge source code, from prerequisite setup through launching your first project.

Prerequisites for SwarmForge Installation

Before installing SwarmForge, ensure your machine has all required dependencies. According to the [README.md](https://github.com/unclebob/swarm-forge/blob/main/README.md#L71-L78), you need:

Tool	Purpose	Installation Notes
zsh	Default shell for SwarmForge scripts	Usually pre-installed on macOS; apt install zsh on Ubuntu
git	Clone repository branches	git --version ≥ 2.x recommended
tmux	Terminal multiplexing for agent sessions	Core dependency for all SwarmForge operations
Babashka (bb)	Native Clojure scripting engine	Install via babashka.org
LLM backend	AI agent inference	One of: codex, claude, copilot, or grok

Verify Babashka installation:

bb --version

Install the get-swarm-forge Helper Script

The SwarmForge installation uses a helper script called get-swarm-forge. Place this script on your PATH so you can invoke it from any directory.

Step 1: Copy the Helper to Your PATH

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

This excerpt follows the installation instructions in [README.md lines 83-89](https://github.com/unclebob/swarm-forge/blob/main/README.md#L83-L89). The ~/cmds directory is a common convention, but ~/bin or any directory in your $PATH works equally well.

Step 2: Initialize Your Forge Directory

Create a dedicated workspace—called the forge—that will hold all packs and projects:

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

Running get-swarm-forge (source: get-swarm-forge script) performs the following automatically:

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

After this command completes, your directory structure resembles:

~/my-swarm-forge/
├── swarmforge/           # Host scripts and runtime

│   ├── scripts/
│   └── conf/
├── packs/
│   ├── two-pack/
│   ├── four-pack/
│   └── six-pack/
└── projects/             # Empty until you create projects

Launch the SwarmForge Dashboard

Start the SwarmForge orchestration layer by running the wrapper script from your forge root:

./swarm

This command executes swarmforge/scripts/swarmforge.sh to:

1. Boot the lieutenant agent (central coordinator)
2. Start the local web dashboard
3. Initialize the tmux session that hosts project agents

The dashboard prints a URL—also written to .swarmforge/dashboard-url—and automatically opens it in your default browser if the open command is available. See the launch instructions in [README.md lines 101-107](https://github.com/unclebob/swarm-forge/blob/main/README.md#L101-L107).

Create Your First Project

With the dashboard running, complete the SwarmForge setup by creating a project:

1. Click New Project in the web UI
2. Enter a project name (e.g., demo)
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:

• mission.md — project objectives and context
• Local swarmforge.conf — pack-specific configuration
• Copy of the selected pack's directory structure

The chosen pack's agents start automatically in dedicated tmux windows.

Optional Environment Configuration

Control SwarmForge behavior with environment variables before running ./swarm:

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

Example with both disabled:

SWARMFORGE_OPEN_BROWSER=0 SWARMFORGE_PREVENT_SLEEP=0 ./swarm

Complete Installation Command Reference

# 1. Install prerequisites (zsh, git, tmux, bb, and your LLM backend)

# 2. Install the get-swarm-forge helper

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

# 3. Create and initialize the forge

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

# 4. Launch the dashboard

./swarm

# 5. Create a project via the web UI

#    → New Project → Name: hello-world → Pack: two-pack → Create

Summary

• Prerequisites: zsh, git, tmux, Babashka (bb), and one LLM backend are mandatory for SwarmForge operation
• Helper script: get-swarm-forge downloads all branches and establishes the packs/ and projects/ directory structure
• Launcher: ./swarm starts the lieutenant, dashboard, and tmux session from your forge root
• Project creation: Use the web dashboard to instantiate projects; each project receives its own mission.md and agent configuration
• No external dependencies: After the initial get-swarm-forge run, SwarmForge operates entirely offline

Frequently Asked Questions

What operating systems support SwarmForge?

SwarmForge runs on any Unix-like system with zsh, git, tmux, and Babashka. macOS and Linux distributions are fully supported. Windows users can run SwarmForge via WSL2 with these tools installed.

Can I install SwarmForge without Babashka?

No. Babashka (bb) is a hard dependency. The get-swarm-forge script and all runtime orchestration in swarmforge/scripts/swarmforge.sh rely on Clojure scripting that Babashka provides natively without a JVM.

Where are my projects stored after installation?

Projects live in the projects/ subdirectory of your forge root—created when you first run get-swarm-forge. Each project receives its own folder with mission.md, local configuration, and working files. The dashboard creates these directories automatically.

How do I switch between different pack configurations?

During project creation, select two-pack, four-pack, or six-pack from the dashboard dropdown. Each pack defines a different agent topology in swarmforge/conf/swarmforge.conf, determining how many specialized agents collaborate on tasks.

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