How to Configure SwarmForge: A Step-by-Step Guide to Role Hierarchies and Trust Settings

Configure SwarmForge by editing two text-based files: swarmforge/swarmforge.conf defines which agents run and in what order, while ~/.config/swarmforge/config.toml stores trust permissions so agents launch without repeated prompts.

SwarmForge orchestrates AI-driven software engineering pipelines through a lightweight configuration system. This guide walks through the two essential files that control agent roles and host permissions, with direct references to the source implementation in the unclebob/swarm-forge repository.

---

The Two Core Configuration Files

SwarmForge configuration splits cleanly between pack-level role definitions and host-level trust settings.

File	Purpose	Location	Format
swarmforge.conf	Role hierarchy and startup order	<repo-root>/swarmforge/swarmforge.conf	Plain text, one role per line
config.toml	Trust levels for pack directories	~/.config/swarmforge/config.toml or $HOME/config.toml	TOML with [[projects]] arrays

---

Configuring the Role Hierarchy in swarmforge.conf

The swarmforge.conf file tells SwarmForge which agents to instantiate, which backend each uses, and what command-line flags to pass.

File Format

Each non-comment line follows this pattern:

RoleName backend-name [--optional-flags]

Comment lines beginning with # are ignored by the parser in swarmforge/scripts/swarmforge.bb (see the parse-config function).

Example Configuration

# Host lieutenant. Default is grok with no extra args.

Lieutenant grok --yolo
Coder codex
Cleaner gpt-4
Architect claude
QA gpt-4

How the Launcher Parses This File

When you run ./swarm, the entry-point script swarmforge/scripts/swarmforge.bb executes:

1. Calls parse-config to read swarmforge/swarmforge.conf
2. Extracts the Lieutenant configuration separately via parse-lieutenant-config
3. Spawns a dedicated tmux window for each role, isolating its git worktree
4. Maintains the order defined in the configuration file

The test suite in test/swarmforge/pack_ui_test.clj validates that this role order is respected by the UI.

Creating Your Own swarmforge.conf

cat > swarmforge/swarmforge.conf <<'EOF'

# Define the role chain for this pack

Lieutenant grok --yolo
Coder codex
Cleaner gpt-4
Architect claude
QA gpt-4
EOF

---

Setting Up Trust Permissions in config.toml

Without trust configuration, SwarmForge prompts you to approve every agent launch. The config.toml eliminates this friction by pre-authorizing specific pack directories.

Manual Trust Configuration

CONFIG="$HOME/.config/swarmforge/config.toml"
mkdir -p "$(dirname "$CONFIG")"
cat >> "$CONFIG" <<EOF

[[projects]]
path = "$(pwd)/packs/six-pack"
trust_level = "trusted"
EOF

Trust Verification Logic

The launcher checks trust status before spawning agents. The test trust-does-not-duplicate-existing-config in the codebase confirms that duplicate entries are handled gracefully—SwarmForge appends new trust records only when the path isn't already present.

Critical Requirement

The path value must be an absolute path. Relative paths will fail the trust check, forcing interactive prompts.

---

Complete Configuration Workflow

Follow this sequence to fully configure SwarmForge:

1. Initialize the pack

   get-swarm-forge six-pack   # or two-pack / four-pack
   
   cd six-pack

2. Define roles — Edit swarmforge/swarmforge.conf with your agent chain

3. Establish trust — Create ~/.config/swarmforge/config.toml with the absolute pack path

4. Launch

   ./swarm

This creates a tmux session with one window per configured role. Agents begin processing cards according to the shared constitution articles (engineering.prompt, workflow.prompt, etc.).

---

Verification: Confirming Correct Role Order

The following Playwright test snippet validates that the dashboard reflects your swarmforge.conf configuration:

const { expect } = require('@playwright/test');

test('roles start in config order', async ({ page }) => {
  await page.goto('http://localhost:3000/dashboard');
  const roleHeaders = await page.$$eval('.role-header', 
    els => els.map(e => e.textContent));
  expect(roleHeaders).toEqual([
    'Lieutenant', 'Coder', 'Cleaner', 'Architect', 'QA'
  ]);
});

---

Handoff Protocol: Beyond Configuration

Agent communication operates independently of configuration files. The handoff protocol—described in swarmforge/handoff-protocol.md and validated by test/swarmforge/handoff_test.clj—uses three shell scripts to coordinate work:

• swarm_handoff.sh — Initiates work transfer
• ready_for_next.sh — Signals completion readiness
• done_with_current.sh — Confirms task finalization

No additional configuration is required to enable this protocol.

---

Summary

• swarmforge.conf defines the role hierarchy, backend selection, and startup order for each pack
• config.toml stores trust permissions to enable automatic agent launches without prompts
• The launcher script swarmforge/scripts/swarmforge.bb parses both files via parse-config and parse-lieutenant-config
• Absolute paths are mandatory in trust entries
• Tmux windows isolate each role's git worktree according to the configuration

---

Frequently Asked Questions

What happens if I don't create a config.toml file?

SwarmForge will prompt you to approve each agent launch interactively. The system functions without trust configuration, but requires manual confirmation for every role instantiation.

Can I use relative paths in the config.toml trust entry?

No. The trust check requires absolute paths. Relative paths will fail validation, causing SwarmForge to treat the pack as untrusted and prompt for approval.

How do I change which AI backend a role uses?

Edit the backend name in swarmforge.conf. For example, change Coder codex to Coder claude or Coder gpt-4. Any backend identifier supported by your SwarmForge installation can be specified.

Where can I find the sample configuration files?

The repository includes a minimal swarmforge.conf at swarmforge/swarmforge.conf (currently four empty comment lines). The README.md provides installation instructions and links to helper scripts for pack initialization.

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