Multi-agent execution

A single model's answer is one data point. Multi-agent execution runs a stage several ways at once and lays the results next to each other, so "which model should I trust?" becomes something you can see rather than guess. There are four modes, set in the stage's execution block.

Multi-agent modes require a license. Single-agent runs and replay are always available.

Choosing a mode

Mode	What it does	You get
parallel	Runs N agents on the same prompt at once.	Every result, side by side, to compare and choose from.
race	Runs N agents at once; the first valid success wins and the rest are cancelled.	One result, fast.
consensus	Parallel, plus a structural analysis of where the outputs agree and differ.	Agreement and divergence, made explicit.
specialist	Assigns named roles (planner, reviewer, tester…), each with its own instructions.	Complementary outputs you can promote together.

Parallel and race use agents

parallel, race, and consensus take a list of agents (2–8 of them). Each agent names a runtime, and optionally a model:

    execution:
      mode: parallel
      agents:
        - runtime: claude-code
          model: sonnet
        - runtime: openrouter
          model: anthropic/claude-opus-4.5
        - runtime: ollama

Every agent gets the identical prompt, the same consumed artifacts, and writes into its own slot directory; nothing mixes. Duplicate runtime-and-model pairs are allowed on purpose: running the same model twice is a fair way to see its variance.

Parallel finishes when every agent reaches a terminal state. The attempt succeeds if at least one agent succeeded with no blocking validation failure.

Race validates each agent the moment it finishes. The first one to succeed and pass its blocking validators wins; the others are cancelled then and there. Their partial output is still saved and marked cancelled; provenance is never thrown away. If they all fail, the attempt fails.

Consensus adds an analysis

Consensus runs exactly like parallel, then compares the outputs structurally and reports:

• the sections that appeared in every candidate,
• the sections that appeared in only some of them, and
• a pairwise similarity score to flag the odd one out.

It's an agreement-and-disagreement report for you; Ringmaster never auto-selects a winner from it. Where the models converge is usually solid; where they split is where your attention is worth most.

Specialist uses roles

Specialist mode is different in intent: the executions aren't competing, they're dividing the work. Each role gets the stage prompt plus its own instructions overlay:

    execution:
      mode: specialist
      roles:
        planner:
          runtime: claude-code
          instructions: |
            You are the planner. Produce plan.md: problem, approach, success criteria.
        security:
          runtime: claude-code
          instructions: |
            You are the security reviewer. Produce security-review.md: top three risks.

Each role's slot is named after the role. Because the outputs are complementary, the review gate lets you promote artifacts from several roles at once: keep plan.md from the planner and security-review.md from the security role. If one role fails, you can still promote the others or re-run just the one that failed.

The comparison view

Whenever an attempt has more than one execution, Ringmaster builds a comparison table: each slot's status, its validation result, how long it took, and (when the runtime reports them) token counts and cost. From there you can open any two outputs in a side-by-side diff before deciding what to promote. The same data is written to a comparison.json in the attempt directory, and you can read it from the command line with ringmaster compare (see the CLI).

How many run at once

Ringmaster caps how many executions run simultaneously (four by default) so a wide fan-out doesn't overwhelm your machine or your rate limits. You can change the cap in Settings. Some local runtimes that serve one request at a time (LM Studio, llama.cpp) are run one after another automatically, regardless of the cap.

Promotion, same as always

Multi-agent or not, the gate is the same: you review the candidates and promote the artifacts you want. Those become canonical and flow downstream. Everything you didn't pick stays in the run's history, with its provenance intact, in case you want to revisit the comparison later.