# What Is a SwarmForge Swarm Topology? A Complete Guide to Configuration-Driven Agent Orchestration

> Discover what a SwarmForge swarm topology is. This guide explains configuration-driven agent orchestration and how agents arrange roles and communication without code.

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

---

**A SwarmForge swarm topology is the structural blueprint that defines how AI agents are arranged, what roles they perform, and how they communicate—entirely through configuration rather than code.**

This article explains the SwarmForge swarm topology system as implemented in `unclebob/swarm-forge`, including how to define, customize, and deploy your own agent orchestrations using the [`swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge.conf) configuration file.

## Understanding the SwarmForge Topology Model

Unlike traditional multi-agent frameworks that hard-code agent relationships in Python or JavaScript, SwarmForge takes a **configuration-driven approach**. The entire shape of your swarm lives in [`swarmforge/swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/swarmforge.conf), making it trivial to prototype new workflows without touching source code.

According to the SwarmForge source code, a topology answers four critical questions:

- **Which agents run** — the roles (e.g., `coder`, `specifier`, `architect`)
- **Where they run** — their git worktrees or the main project directory
- **How work flows** — handoff patterns between agents
- **What backend powers each** — the LLM provider (`grok`, `codex`, `claude`)

## The Core Configuration File: [`swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge.conf)

The [`swarmforge/swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/swarmforge.conf) file is the single source of truth for your swarm topology. Every topology begins with a **host lieutenant** declaration followed by **window definitions** that instantiate each agent.

### Window Definition Syntax

Each window line follows this pattern as documented in the README:

```

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

```

| Component | Purpose |
|-----------|---------|
| `window` or `window-invisible` | Creates a visible tmux pane or hidden background agent |
| `<role>` | Name matching a file in `swarmforge/roles/<role>.prompt` |
| `<agent>` | Backend LLM (e.g., `grok`, `codex`, `claude`) |
| `<worktree>` | Git worktree location (`master` or subdirectory under `.worktrees/`) |
| `task` or `batch` | Execution mode—interactive task card or batch processing |
| `forward-only`, `back-one`, `back-all` | **Propagation tokens** controlling merge-only copy distribution |

## Propagation Tokens and Work Flow

The SwarmForge swarm topology uses **propagation tokens** to control how completed work moves through the chain. These tokens appear in [`swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge.conf) and govern handoff behavior without requiring code changes:

- **`forward-only`** — Work moves strictly to the next role in sequence; no backward copies
- **`back-one`** — Delivers a merge-only copy to the immediate previous role
- **`back-all`** — Broadcasts merge-only copies to all earlier roles in the topology

This mechanism, described in [`swarmforge/handoff-protocol.md`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/handoff-protocol.md), lets you build sophisticated feedback loops. For example, a `refactorer` with `back-one` can inform the `coder` of changes without disrupting the forward workflow, while `back-all` ensures the entire upstream chain stays synchronized.

## Practical Example: Four-Pack Topology

Here's a complete, runnable [`swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge.conf) that demonstrates a realistic SwarmForge swarm topology:

```conf

# Host lieutenant (defaults to grok)

Lieutenant grok --yolo

# Define the swarm windows

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

```

**Topology breakdown:**

1. **`specifier`** — Runs in `master` worktree using `codex`, defines requirements
2. **`coder`** — Runs isolated in `.worktrees/coder/` using `grok`, implements specifications
3. **`refactorer`** — Reviews code with `back-one` propagation to notify coder of changes
4. **`architect`** — Batch-mode oversight with `back-all` to synchronize entire chain

This configuration creates four tmux sessions, four git worktrees, and establishes the handoff protocol automatically when you run `./swarm`.

## Starting and Inspecting Your Swarm

Deploying a configured topology requires two commands:

```bash

# Launch the dashboard and lieutenant

./swarm

# Instantiate a specific topology for a new project

./swarm new-project MyApp four-pack

```

The `./swarm` executable reads [`swarmforge/swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/swarmforge.conf), validates that all referenced role prompts exist in `swarmforge/roles/`, then constructs the tmux environment and worktrees.

To verify your topology configuration, inspect individual role prompts:

```sh
cat swarmforge/roles/coder.prompt

```

Each `.prompt` file contains the system instructions passed to the backend LLM. Modifying these changes agent behavior without altering the topology structure—clean separation of **structure** (config) from **behavior** (prompts).

## Extending Topologies with `project.prompt`

Packs can specialize the base SwarmForge swarm topology through an optional `project.prompt` file. This file, typically found at `swarmforge/constitution/articles/project.prompt`, allows project-specific extensions that augment or override default behaviors.

The hierarchy works as follows:

- **[`swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge.conf)** — Defines universal topology shape
- **`project.prompt`** — Adds project-contextual instructions and local topology adaptations

This layering lets teams share base configurations while customizing for domain-specific workflows.

## Key Files in the Topology System

| File | Function |
|------|----------|
| [`swarmforge/swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/swarmforge.conf) | Primary topology definition (windows, roles, propagation) |
| `swarmforge/roles/*.prompt` | Per-role behavior instructions |
| `swarmforge/constitution/articles/workflow.prompt` | Default workflow rules applied to all packs |
| `swarmforge/constitution/articles/project.prompt` | Optional project-specific topology extensions |
| [`swarmforge/handoff-protocol.md`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/handoff-protocol.md) | Message format specification for inter-agent communication |

## Summary

- **SwarmForge swarm topology** is declared in [`swarmforge/swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/swarmforge.conf), not encoded in scripts
- **Window definitions** combine roles, backends, worktrees, and propagation tokens into agent instances
- **Propagation tokens** (`forward-only`, `back-one`, `back-all`) control how merge-only copies flow backward through the chain
- **Role prompts** in `swarmforge/roles/` decouple behavior from structure, enabling rapid experimentation
- **Project-specific extensions** via `project.prompt` allow topology specialization without forking configurations

## Frequently Asked Questions

### What makes SwarmForge's topology approach different from other agent frameworks?

Most frameworks embed agent relationships in executable code, requiring redeployment to change workflows. SwarmForge's configuration-driven approach means you edit [`swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge.conf) and restart—the topology updates immediately without code changes. This aligns with SwarmForge's philosophy of treating agent orchestration as infrastructure rather than application logic.

### How do propagation tokens affect actual agent behavior?

Propagation tokens only control **merge-only copy distribution**, not task card movement. When an agent completes work, the task card always advances forward. The token determines whether earlier agents receive read-only copies of that work: `forward-only` sends nothing backward, `back-one` notifies the immediate predecessor, and `back-all` broadcasts to the entire upstream chain. This keeps agents informed without disrupting their current tasks.

### Can I mix visible and invisible windows in the same topology?

Yes. Use `window` for agents you want to observe in the tmux dashboard, and `window-invisible` for background processors. The `architect` in the four-pack example typically runs invisible in batch mode, while `coder` might be visible for interactive debugging. The choice affects only UI presentation, not functional capabilities.

### What happens if a role referenced in [`swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge.conf) has no matching prompt file?

SwarmForge validates topology on startup and will fail with an error if `swarmforge/roles/<role>.prompt` is missing. Every window declaration must reference a role with a corresponding prompt file. This enforcement ensures agents always have explicit behavioral instructions.