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

> Learn how to configure SwarmForge using swarmforge.conf. Define agent roles, LLM binaries, and worktrees in this comprehensive guide to setting up your swarm topology.

- Repository: [Robert C. Martin/swarm-forge](https://github.com/unclebob/swarm-forge)
- Tags: how-to-guide
- Published: 2026-08-29

---

**To configure SwarmForge, create a [`swarmforge/swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/handoff-protocol.md) | Specification for inter-agent hand-off payloads |

The `forge.bb` script reads [`swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/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

```conf
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

```conf
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

```conf
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`](https://github.com/unclebob/swarm-forge/blob/main/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:

```bash
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:

```bash
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:

```bash

# 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:

```conf
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`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge.conf) fails to load:

1. Verify file exists at [`swarmforge/swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/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.