How to Configure SwarmForge Using swarmforge.conf: A Complete Guide

To configure SwarmForge, create a swarmforge/swarmforge.conf file where each line defines an agent window with its role, LLM binary, git worktree, and optional hand-off behavior—then run ./swarm to launch the entire swarm topology.

SwarmForge is an open-source multi-agent orchestration framework by Robert C. Martin (unclebob) that runs LLM-driven development workflows inside tmux sessions. The swarmforge.conf file is the sole declarative source of truth for your swarm's shape, making configurations portable and reproducible across projects and machines.

File Location and Structure

SwarmForge expects its configuration in a predictable location within your project:

Path	Purpose
swarmforge/swarmforge.conf	Main configuration file defining all agent windows
swarmforge/roles/<role>.prompt	System prompts for each role referenced in the conf
swarmforge/scripts/forge.bb	Bash-Bite launch script that parses the configuration
swarmforge/handoff-protocol.md	Specification for inter-agent hand-off payloads

The forge.bb script reads swarmforge.conf at startup and builds the complete agent topology from its contents. No hard-coded shell variables or command-line flags are required—you define everything in this single file.

swarmforge.conf Syntax

Each non-empty line in swarmforge.conf follows this exact structure:

window[-invisible] <role> <agent> <worktree> [task|batch] [forward-only|back-one|back-all] [extra-cli-args...]

Required Fields

• window or window-invisible — Visibility flag. window creates a visible terminal surface; window-invisible runs the agent headlessly in tmux (pack default).
• <role> — Logical role name. Must have a matching prompt file at swarmforge/roles/<role>.prompt.
• <agent> — The LLM binary to execute (e.g., grok, codex, claude, copilot).
• <worktree> — Git worktree name for agent isolation. Use master to run in the main project directory.

Optional Modifiers

Modifier	Behavior
task	Single hand-off processing (default)
batch	Consume all queued hand-offs of equal priority in one batch
forward-only	Hand-off propagates only to next window (default)
back-one	Also queue merge-only copy to previous window
back-all	Copy to every earlier window in the swarm
extra-cli-args...	Additional arguments passed directly to the agent binary

The full syntax specification is documented in the README at lines 306-321.

Host Lieutenant Configuration

The first line of swarmforge.conf may optionally declare a host lieutenant—a single master agent that runs instead of a multi-window swarm:

Lieutenant <agent> [extra-cli-args...]

If omitted, SwarmForge defaults to grok with no arguments. As shown in the repository's default configuration, this provides a minimal entry point for simple projects.

Pack Defaults and Inheritance

When you add SwarmForge to a project via get-swarm-forge, the installation includes pack-level defaults. Any role not explicitly defined in your project's swarmforge.conf inherits from these pack defaults, documented in the README at lines 331-338. This lets you override only the specific roles you need while keeping common configurations standardized.

Practical Configuration Examples

Minimal Host-Only Setup

Lieutenant grok --yolo

Starts a single host agent using grok with the --yolo flag. No tmux windows are created—just one persistent agent in the main directory.

Four-Pack Swarming Topology

window-invisible specifier codex master --yolo
window-invisible coder grok coder
window-invisible refactorer grok refactorer back-one
window-invisible architect codex architect batch back-all --yolo

This matches the canonical example from the README (lines 556-563). It defines four specialized agents:

• specifier — Runs in master worktree, processes single tasks
• coder — Isolated in coder worktree, forward-only propagation
• refactorer — Returns hand-offs one step backward for review
• architect — Batch processes with full backward visibility to all prior agents

Mixed Visibility Configuration

window specifier codex master --yolo
window-invisible coder grok coder
window refactorer grok refactorer back-one
window-invisible architect codex architect batch back-all

Here, specifier and refactorer have visible terminal windows for monitoring, while coder and architect run silently. This pattern conserves screen space for less critical roles.

How forge.bb Processes swarmforge.conf

The launch script swarmforge/scripts/forge.bb executes this sequence:

1. Parse — Reads swarmforge.conf via fs/path, builds agent list, resolves pack defaults (lines 56-63)
2. Prepare worktrees — Creates git worktrees under .worktrees/ for each unique <worktree> value
3. Initialize tmux — Establishes dedicated socket at .swarmforge/tmux-socket
4. Spawn windows — Creates visible or invisible tmux windows per configuration lines
5. Launch agents — Executes LLM binaries with hand-off protocol flags and extra CLI arguments
6. Route hand-offs — Manages inter-agent communication based on propagation tokens

Creating a Custom swarmforge.conf

First, initialize your project structure:

mkdir -p swarmforge/roles

# Create the configuration file

cat > swarmforge/swarmforge.conf <<'EOF'

# Host lieutenant for simple sessions

Lieutenant grok --yolo

# Visible coding agent in main worktree

window coder copilot master --yolo

# Background reviewer with batch processing

window-invisible reviewer codex wt-reviewer batch back-one

# Architect with strict permissions in isolated worktree

window architect claude wt-arch task --dangerously-skip-permissions
EOF

Then add corresponding role prompts:

cat > swarmforge/roles/coder.prompt <<'EOF'
You are a senior software engineer. Write clean, testable code. Ask clarifying questions when requirements are ambiguous.
EOF

cat > swarmforge/roles/reviewer.prompt <<'EOF'
You are a code reviewer. Identify bugs, suggest improvements, verify test coverage. Be constructive and specific.
EOF

cat > swarmforge/roles/architect.prompt <<'EOF'
You are a systems architect. Design resilient, scalable solutions. Document trade-offs and rationale.
EOF

Launch the swarm:

# With specific terminal emulator

SWARMFORGE_TERMINAL=ghostty ./swarm

# Or auto-detect terminal

./swarm

Advanced Propagation Patterns

The propagation token controls hand-off visibility across your swarm topology:

• forward-only: Linear pipeline—each agent passes to the next
• back-one: Ring-buffer pattern—current agent's output returns to previous agent for merge review
• back-all: Broadcasting pattern—current agent's output reaches all upstream agents

Use batch back-all for aggregator roles that need global context:

window coordinator claude wt-coord batch back-all --verbose

This ensures the coordinator sees every card processed by any prior agent before making synthesis decisions.

Debugging Configuration Issues

When swarmforge.conf fails to load:

1. Verify file exists at swarmforge/swarmforge.conf (not project root)
2. Check that each <role> has matching swarmforge/roles/<role>.prompt
3. Ensure <agent> binaries are in $PATH
4. Validate worktree names contain no spaces or special characters
5. Review forge.bb output for parse errors at lines 56-63

Summary

• swarmforge.conf is the single declarative source for SwarmForge topology
• Each line defines one agent with role, LLM binary, worktree, and hand-off behavior
• window / window-invisible control terminal visibility
• Lieutenant declaration enables single-agent mode
• task/batch and propagation tokens fine-tune workflow patterns
• The forge.bb script parses, validates, and executes the configuration without additional flags

Frequently Asked Questions

What happens if I omit the Lieutenant line?

SwarmForge defaults to Lieutenant grok with no extra arguments. The swarm will start with a single host agent using the grok binary. Multi-window configurations require explicit window declarations—no automatic fallback occurs.

Can I use the same role multiple times with different agents?

Yes. The <role> determines which prompt file loads, but you can reference it across multiple lines with different <agent> binaries or worktrees. Each line creates an independent agent instance with that role's system message.

Why does my agent fail to start with "role not found"?

The <role> field must exactly match a filename in swarmforge/roles/ with .prompt extension. A role coder requires swarmforge/roles/coder.prompt. The error originates in forge.bb during prompt resolution before agent launch.

How do I migrate a swarmforge.conf between projects?

Copy the file to the new project's swarmforge/ directory, ensure matching role prompts exist, and verify that referenced <agent> binaries are installed. Worktrees are recreated automatically on first run. The swarm topology reproduces identically regardless of host machine.

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