How to Configure Different Agent Backends (Claude, Codex, Copilot, Grok) per Role in SwarmForge

To configure different AI backends per role in SwarmForge, edit the 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 file, where each role declaration includes its assigned backend agent.

Understanding the Configuration File Format

SwarmForge reads role definitions from swarmforge/swarmforge.conf using a specific line-based syntax. Each configuration line follows this pattern:

window <role> <agent> <worktree> [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:

• <role> — The identifier for the role (e.g., coder, architect).
• <agent> — The backend to launch (claude, codex, copilot, or grok).
• <worktree> — 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:

#{"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 as follows:

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

# 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 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 <role> <agent> <worktree> [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.

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