# How to Configure Different Agent Backends (Claude, Codex, Copilot, Grok) per Role in SwarmForge > Configure different AI agent backends like Claude, Codex, Copilot, and Grok per role in SwarmForge by editing the swarmforge.conf file. Learn how to assign specific agents to roles for tailored AI assistance. - Repository: [Robert C. Martin/swarm-forge](https://github.com/unclebob/swarm-forge) - Tags: how-to-guide - Published: 2026-08-10 --- **To configure different AI backends per role in SwarmForge, edit the [`swarmforge/swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/swarmforge.conf) file and specify the agent name (claude, codex, copilot, or grok) in the second field of each role definition line.** SwarmForge is an open-source multi-agent orchestration framework from unclebob/swarm-forge that enables teams to run specialized AI agents collaboratively. Configuring distinct backends for different roles allows you to leverage Claude for architectural planning while using Codex for implementation, all within the same swarm. This configuration is controlled through the [`swarmforge/swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/swarmforge.conf) file, where each role declaration includes its assigned backend agent. ## Understanding the Configuration File Format SwarmForge reads role definitions from [`swarmforge/swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/swarmforge.conf) using a specific line-based syntax. Each configuration line follows this pattern: ```text window [receive-mode] [extra-args...] ``` In `swarmforge/scripts/swarmforge.bb`, the parser extracts these fields to build a role description map. The code processing these lines (around lines 49-57) splits each configuration entry and assigns the second token to the `:agent` key in the role map. The fields are: - **``** — The identifier for the role (e.g., `coder`, `architect`). - **``** — The backend to launch (`claude`, `codex`, `copilot`, or `grok`). - **``** — The git worktree directory (`none`, `master`, or a custom name). - **`[receive-mode]`** — Optional delivery mode: `task` (default) or `batch`. - **`[extra-args...]`** — Additional arguments passed directly to the backend binary. ## Supported Agent Backends and Validation SwarmForge validates every agent declaration against an explicit allowlist. In `swarmforge/scripts/swarmforge.bb`, lines 169-173 define the supported set: ```clojure #{"claude" "codex" "copilot" "grok"} ``` If the configuration file specifies an agent not included in this set, SwarmForge aborts immediately with an "Unsupported agent" error. This validation ensures that only the four officially supported backends can be assigned to roles, preventing runtime failures from typos or incompatible integrations. ## Configuration Examples ### Assigning Distinct Backends to Each Role To maximize the strengths of different AI models, assign a unique backend to each role in your swarm. Edit [`swarmforge/swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/swarmforge.conf) as follows: ```text # swarmforge/swarmforge.conf window coder codex coder-wt window cleaner copilot cleaner-wt window architect claude architect-wt window hardender grok hardender-wt task --max-tokens 2000 ``` In this configuration: - The `coder` role uses **Codex** operating in the `coder-wt` worktree. - The `cleaner` role uses **Copilot** in the `cleaner-wt` worktree. - The `architect` role uses **Claude** for high-level design tasks. - The `hardender` role uses **Grok** with additional launch arguments (`--max-tokens 2000`) passed to the binary. ### Using Default Backends with Selective Overrides You can standardize on one backend for most roles while overriding specific roles that require different capabilities: ```text # swarmforge/swarmforge.conf window coder codex coder-wt window cleaner codex cleaner-wt window tester codex tester-wt window architect claude architect-wt ``` Here, three roles default to **Codex**, while the `architect` role explicitly requests **Claude** for specialized architectural reasoning. ## How SwarmForge Processes Backend Selection The backend assignment flow involves three stages in `swarmforge/scripts/swarmforge.bb`: 1. **Parsing**: Lines 49-57 extract tokens from each `window` declaration, constructing a map that includes the `:agent` key. 2. **Validation**: Lines 169-173 check the extracted agent string against the allowlist `#{"claude" "codex" "copilot" "grok"}`. 3. **Execution**: Around lines 339-340, SwarmForge constructs the launch command using the validated agent identifier, appending any extra arguments specified in the configuration line. This architecture ensures that backend selection is both flexible for users and strictly validated before any agent processes spawn. ## Summary - Configure backends by editing [`swarmforge/swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/swarmforge.conf) and setting the agent field in each `window` declaration. - Valid backends are `claude`, `codex`, `copilot`, and `grok`, validated at lines 169-173 in `swarmforge/scripts/swarmforge.bb`. - The syntax is `window [receive-mode] [extra-args...]`. - SwarmForge parses these assignments (lines 49-57), validates them, and constructs launch commands (lines 339-340) to instantiate the correct backend per role. ## Frequently Asked Questions ### What is the exact syntax for specifying a backend in swarmforge.conf? Use the `window` directive followed by the role name, agent backend, worktree, and optional arguments. For example: `window architect claude architect-wt`. The agent must be one of `claude`, `codex`, `copilot`, or `grok`. ### What happens if I specify an unsupported agent backend? SwarmForge aborts with an "Unsupported agent" error. The validation logic at lines 169-173 in `swarmforge/scripts/swarmforge.bb` explicitly checks against the allowlist `#{"claude" "codex" "copilot" "grok"}`, rejecting any other values before attempting to launch processes. ### Can I pass additional arguments to specific agent backends? Yes. Include extra arguments after the optional `receive-mode` field in the configuration line. For example: `window hardender grok hardender-wt task --max-tokens 2000`. These arguments are appended to the backend launch command constructed around lines 339-340 of the swarmforge script. ### Where does SwarmForge validate the agent backend names? Validation occurs in `swarmforge/scripts/swarmforge.bb` at lines 169-173, where the parser checks the extracted agent token against a Clojure set containing the four supported strings. This check happens during configuration loading, before any agent processes are spawned.