How to Configure Different Agent Roles and Their Worktrees in SwarmForge

Configure agent roles and worktrees in SwarmForge by editing 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, 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 Configuration Format

Each line in swarmforge/swarmforge.conf declares one window (agent role) using the following structure:

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

The five components are:

• <role> — A unique identifier (no underscores) used to locate the prompt file at swarmforge/roles/<role>.prompt.
• <agent> — The backend driving the role. Valid options are claude, codex, copilot, or grok.
• <worktree> — 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/<worktree>/.
• [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/<worktree>/.

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/<role>.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

# 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

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

# 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 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/<role>.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 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.

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