# SwarmForge Configuration File Format: A Complete Guide to swarmforge.conf > Explore the SwarmForge configuration file format. Learn how to define tmux windows using the declarative swarmforge.conf syntax for efficient agent management. - Repository: [Robert C. Martin/swarm-forge](https://github.com/unclebob/swarm-forge) - Tags: api-reference - Published: 2026-08-09 --- **The [`swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge.conf) file uses a declarative line-based syntax where each non-comment line declares a tmux window with the format `window [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`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/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: ```conf window [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`](https://github.com/unclebob/swarm-forge/blob/main/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 ```conf 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 ```conf 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 ```conf 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`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge.conf) File" section, this pattern establishes a coordinator-managed swarm with segregated worktrees for each specialization. ## Summary - **Syntax**: Each line must follow `window [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`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/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.