# How to Configure Different Agent Roles and Their Worktrees in SwarmForge > Learn to configure SwarmForge agent roles and worktrees by editing the swarmforge.conf file. Define backends, worktrees, and runtime parameters for automated setup. - Repository: [Robert C. Martin/swarm-forge](https://github.com/unclebob/swarm-forge) - Tags: how-to-guide - Published: 2026-08-09 --- **Configure agent roles and worktrees in SwarmForge by editing [`swarmforge/swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/swarmforge.conf) to define each role's backend, worktree assignment, and runtime parameters; the orchestration script automatically validates the configuration, creates git worktrees, and initializes tmux sessions.** SwarmForge discovers the topology of a multi-agent swarm from a single configuration file rather than scattered environment variables or command-line flags. By defining roles, backends, and worktree mappings in [`swarmforge/swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/swarmforge.conf), you control how each agent operates within its own isolated git context. This guide explains the configuration syntax, validation logic, and worktree resolution based on the unclebob/swarm-forge source code. ## Understanding the [`swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge.conf) Configuration Format Each line in [`swarmforge/swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/swarmforge.conf) declares one **window** (agent role) using the following structure: ```text window [receive-mode] [extra-args...] ``` The five components are: - **``** — A unique identifier (no underscores) used to locate the prompt file at `swarmforge/roles/.prompt`. - **``** — The backend driving the role. Valid options are `claude`, `codex`, `copilot`, or `grok`. - **``** — The git worktree assignment. Use `master` or `none` to run in the main checkout, or specify a custom name to create an isolated worktree under `.worktrees//`. - **`[receive-mode]`** — Optional. Either `task` (default) for single-task handoffs or `batch` for grouped task processing. - **`[extra-args...]`** — Optional. Additional CLI arguments passed verbatim to the backend (e.g., `--temperature 0.7`). ## How SwarmForge Parses and Validates Role Configurations During startup, the `parse-config` function in `swarmforge/scripts/swarmforge.bb` (lines [149‑179]) reads and tokenizes the configuration file. The parser validates each row to ensure: - The role name contains no underscores and is unique. - The backend agent is one of the supported values (`claude`, `codex`, `copilot`, `grok`). - The receive mode is either `task` or `batch` when specified. If the configuration contains duplicate worktree names across different roles, SwarmForge aborts immediately. The duplicate-worktree check at lines [65‑66] of `swarmforge.bb` prevents filesystem collisions before any git operations occur. ## Worktree Resolution and Creation SwarmForge resolves abstract worktree names to concrete filesystem paths through the `worktree-path-for-name` helper (lines [71‑73] in `swarmforge.bb`): - **`master`** or **`none`** — The role operates directly in the main repository checkout (`:working-dir`). These values do not create entries under `.worktrees/`. - **Custom names** — SwarmForge creates a dedicated git worktree at `.worktrees//`. When custom worktrees are specified, the `prepare-worktrees!` function (lines [51‑60]) executes `git worktree add` to materialize the directory structure. Subsequently, `sync-worktree-scripts!` (lines [70‑86]) copies role-specific scripts and state into each worktree, ensuring agents operate with the correct context and tooling. ## Runtime Configuration Generation After validation and worktree preparation, SwarmForge persists the runtime topology to `.swarmforge/roles.tsv` via `write-roles-file!` (lines [204‑215]). This tab-separated file maps each role to its resolved worktree path, backend agent, and tmux session ID. Role-specific instructions are injected through prompt files stored at `swarmforge/roles/.prompt`. During agent initialization, `write-agent-instruction-file!` (lines [301‑305]) reads these files and embeds their contents into the agent's runtime instruction set. ## Practical Configuration Examples ### Three Roles with Dedicated Worktrees ```text # swarmforge/swarmforge.conf window coder codex coder window cleaner codex cleaner task --temperature 0.2 window architect grok architect batch --always-approve ``` This configuration creates three isolated worktrees: - **coder** — Runs on the `codex` backend in `.worktrees/coder/` with default task-based handoffs. - **cleaner** — Uses `codex` in `.worktrees/cleaner/`, receives individual tasks, and passes `--temperature 0.2` to the backend. - **architect** — Runs on `grok` in `.worktrees/architect/`, processes tasks in batches, and enables automatic approval. ### Mixed Master and Dedicated Worktrees ```text # swarmforge/swarmforge.conf window specifier claude master window coder codex coder ``` Here, the **specifier** role runs directly in the main checkout (`master`), while **coder** receives its own dedicated worktree at `.worktrees/coder/`. ### Role Prompt File Create the corresponding prompt file for each role: ```text # swarmforge/roles/coder.prompt coder ``` Only the role name is required, though you can append additional system instructions. SwarmForge injects this content into the agent's instruction file during session initialization. ## Summary - **Edit [`swarmforge/swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/swarmforge.conf)** to declare agent roles, backends, and worktree assignments in a single location. - **Use `master` or `none`** for roles that should operate in the main repository checkout; use custom names to spawn isolated git worktrees under `.worktrees/`. - **Avoid duplicate worktree names** across roles to prevent startup failures. - **Leverage extra arguments** to pass backend-specific flags like temperature settings or approval modes. - **Store role prompts** in `swarmforge/roles/.prompt` to customize agent behavior per role. ## Frequently Asked Questions ### What happens if I assign the same worktree name to two different roles? SwarmForge aborts during startup with an error. The duplicate-worktree check at lines [65‑66] of `swarmforge/scripts/swarmforge.bb` enforces unique worktree mappings to prevent filesystem conflicts and ensure each agent operates in a distinct context. ### Can I switch a role from one backend to another without restarting? No. SwarmForge parses [`swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge.conf) once at startup via the `parse-config` function. To change a role's backend from `codex` to `claude`, edit the configuration file and restart the SwarmForge orchestration script. ### What is the difference between `master` and `none` worktree values? Both values cause the role to run in the main repository checkout (`:working-dir`) rather than a dedicated subdirectory. However, `none` explicitly signals that no `.worktrees/` entry should be created, while `master` semantically indicates the primary branch context. Functionally, they produce identical runtime behavior. ### Where does SwarmForge store the active role-to-worktree mappings? The runtime topology is written to `.swarmforge/roles.tsv` by the `write-roles-file!` function (lines [204‑215] in `swarmforge.bb`). This generated file contains tab-separated values mapping each role name to its resolved worktree path, backend agent, and tmux session identifier.