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

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 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, 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

The 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 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, 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 that demonstrates a realistic SwarmForge swarm topology:

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

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

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 — 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	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	Message format specification for inter-agent communication

Summary

• SwarmForge swarm topology is declared in 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 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 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.

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