SwarmForge Configuration File Format: A Complete Guide to swarmforge.conf

The swarmforge.conf file uses a declarative line-based syntax where each non-comment line declares a tmux window with the format window <role> <agent> <worktree> [task|batch] [extra-cli-args…].

The SwarmForge configuration file format defines how multi-agent swarms orchestrate tmux sessions, git worktrees, and AI backends. Located in the unclebob/swarm-forge repository, swarmforge.conf serves as the single source of truth for declaring which roles run which agents and how they process handoffs.

The Core Syntax Structure

Every operational line in swarmforge.conf must begin with the literal keyword window followed by positional arguments. The parser (parse-config in swarmforge/scripts/swarmforge.bb) strictly validates this syntax at lines 29-33, aborting with an error if the keyword is missing or malformed.

The complete syntax follows this pattern:

window <role> <agent> <worktree> [receive-mode] [extra-cli-args…]

Blank lines and lines starting with # are ignored by the parser, allowing for documentation and visual separation between window declarations.

Field Specifications and Validation

Each field in the configuration line undergoes specific validation according to the parser implementation in swarmforge/scripts/swarmforge.bb.

Required Fields

Role — A symbolic identifier for the window that must be unique within the file. The parser at lines 60-64 explicitly rejects any role name containing underscores to prevent shell-related parsing issues.

Agent — The AI backend driving the role. Valid values include claude, codex, copilot, and grok. The validation logic at lines 69-71 ensures unsupported agents trigger immediate configuration errors.

Worktree — Specifies the git context for the role. The value master or none indicates operation in the main working directory, while any other name creates an isolated worktree under .worktrees/. Lines 65-68 enforce that duplicate worktree names (except master/none) are prohibited to prevent file system collisions.

Optional Fields

Receive Mode — Controls handoff consumption behavior. The parser recognizes two modes at lines 51-55:

• task (default): Processes one handoff at a time sequentially
• batch: Consumes all queued handoffs of equal priority in a single operation

Extra CLI Arguments — Any remaining tokens after the receive mode are passed verbatim to the backend CLI. As implemented at lines 56-58, this allows injection of custom flags such as --yolo or --dangerously-skip-permissions without modifying the core SwarmForge scripts.

Configuration File Location and Parsing

The configuration file resides at swarmforge/swarmforge.conf within runnable branches (such as two-pack, four-pack, or six-pack). When SwarmForge initializes, the parse-config function (lines 29-93) reads this file, validates each entry against the schema, and constructs role descriptors that drive tmux session creation.

The first window declared in the file assumes special significance as the cleanup window; terminating this session triggers shutdown of the entire swarm.

Practical Configuration Examples

Minimal Three-Agent Setup

window coordinator codex master
window coder codex coder
window architect codex architect

This configuration creates three tmux windows: a coordinator operating in the master worktree, and two specialist roles (coder and architect) each with dedicated worktrees.

Advanced Configuration with Receive Modes

window coordinator codex master
window coder copilot coder batch --yolo
window architect claude architect task --dangerously-skip-permissions

Here, the coder role processes handoffs in batch mode while passing the --yolo flag to the Copilot CLI, whereas the architect uses Claude in strict task mode with permission skipping enabled.

Full Production Swarm

window coordinator codex master
window coder codex coder
window refactorer codex refactorer
window architect codex architect

As documented in the README's "The swarmforge.conf File" section, this pattern establishes a coordinator-managed swarm with segregated worktrees for each specialization.

Summary

• Syntax: Each line must follow window <role> <agent> <worktree> [mode] [args]
• Validation: Roles cannot contain underscores, agents must be supported backends, and worktrees must be unique (except master/none)
• Modes: task processes single handoffs; batch processes queues of equal priority
• Location: File lives at swarmforge/swarmforge.conf within runnable branches
• Special Role: The first declared window becomes the cleanup coordinator

Frequently Asked Questions

Where does the swarmforge.conf file live?

According to the unclebob/swarm-forge repository structure, the configuration file must be placed at swarmforge/swarmforge.conf inside a runnable branch (e.g., two-pack, four-pack). The parse-config function in swarmforge/scripts/swarmforge.bb specifically targets this path when initializing the swarm.

What agents are supported in SwarmForge?

The parser validates against four supported agents: claude, codex, copilot, and grok. Attempting to specify any other agent value at lines 69-71 of swarmforge/scripts/swarmforge.bb results in a configuration error and immediate termination.

What is the difference between task and batch receive modes?

The task mode (default) processes handoffs one at a time in priority order, suitable for sequential workflows. The batch mode, as implemented at lines 51-55, consumes all queued handoffs of equal priority simultaneously, optimizing for parallel processing when order within a priority level does not matter.

Can I pass custom arguments to the AI backend?

Yes. Any tokens following the optional receive mode are captured as extra-cli-args and passed verbatim to the agent's CLI command. This mechanism at lines 56-58 enables backend-specific flags without requiring modifications to the core SwarmForge orchestration logic.

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