Multi-Agent Runs

CORAL's multi-agent mode lets several agents work on the same task simultaneously, sharing discoveries through notes and skills.

Configuration

agents:
  count: 4          # Spawn 4 agents
  model: sonnet     # All use the same model

Or override at launch:

coral start -c task.yaml agents.count=4

Mix-and-match runtimes

When you want to compare different agent runtimes (or different models within the same runtime) on the same task, use agents.assignments instead of agents.count. Each entry spawns its own group of agents with its own runtime / model / runtime_options:

agents:
  # agents.count is ignored when assignments is set.
  assignments:
    - runtime: claude_code
      model: opus
      count: 2
    - runtime: codex
      model: gpt-5.4
      count: 1
    - runtime: opencode
      model: openai/gpt-5
      count: 1

This spawns four agents (agent-1 through agent-4), each with its own runtime-native shared directory (.claude, .codex, .opencode, ...). Notes, skills, and the attempt leaderboard live in .coral/public/ and are symlinked into every agent's shared directory, so all agents still see each other's work even though they're running different CLIs.

Empty fields on an assignment inherit from the top-level agents.* defaults (or from the runtime's default model when only runtime is set).

Mix-and-match runs require run.session=tmux or run.session=local — run.session=docker is single-runtime only.

Multi-island runs

Multi-island mode splits a multi-agent run into isolated islands. Agents on the same island share attempts, notes, skills, heartbeat state, and roles. Agents on different islands cannot directly see each other's shared state from inside their worktrees, so each island can explore a different region of the solution space without immediately converging on the same ideas.

agents:
  count: 4

islands:
  count: 2

Or override at launch:

coral start -c task.yaml agents.count=4 islands.count=2

islands.count must be no larger than the total agent count. With agents.assignments, the total is the sum of all assignment count values.

CORAL partitions agents round-robin and prefixes IDs by birth island. A four-agent, two-island run starts as:

island 0: 0-agent-1, 0-agent-2
island 1: 1-agent-1, 1-agent-2

The prefix is the birth island, not necessarily the current island. If migration later moves 1-agent-2 to island 0, it keeps the ID 1-agent-2.

Island-scoped CLI behavior

From inside an agent worktree, CORAL reads .coral_island and scopes commands to that agent's current island:

coral status          # current island's agents and leaderboard
coral log             # current island's attempts
coral notes --recent  # current island's notes
coral skills          # current island's skills
coral heartbeat       # current island's heartbeat config

From outside an agent worktree, read-only commands aggregate across islands so operators can inspect the whole run. Mutating heartbeat commands must be run from an agent worktree so CORAL knows which island to update.

Migration

Migration is enabled by default when islands.count > 1. A migration cycle selects strong agents from their current islands and moves up to migration.max_per_cycle agents without worsening island roster balance.

islands:
  count: 2
  migration:
    enabled: true
    every: 50
    rank_window: 20
    min_evals: 3
    dest_weighting: score     # score | uniform | round_robin
    max_per_cycle: 2
    notify_island: true

When an agent migrates, its role, per-agent heartbeat config, attempts, and eval logs move with it. Notes and skills stay on the source island as island-local knowledge. The agent's worktree symlinks and .coral_island breadcrumb are repointed to the destination island.

Full task.yaml example

A complete task.yaml that runs MNIST with four agents across three runtimes:

task:
  name: "MNIST"
  description: |
    Classify handwritten digits (0-9) from MNIST.

    Your program (`solution.py`) must define `run(train_path, test_path)` that
    returns a numpy int array of shape (10000,) with predicted labels.
  tips: |
    Metric is classification accuracy (higher is better, 0-1 scale).

grader:
  timeout: 300
  direction: maximize
  args:
    program_file: "solution.py"
    train_file: "data/train.npz"
    test_file: "data/test.npz"

agents:
  # Top-level fields act as defaults for any assignment that omits them.
  # `count` is IGNORED when `assignments` is set — total agents = sum of
  # assignment counts (here: 2 + 1 + 1 = 4).
  runtime: claude_code
  model: opus
  max_turns: 200

  assignments:
    # Two Claude Code agents on Opus (inherits runtime=claude_code from above)
    - model: opus
      count: 2

    # One Codex agent on gpt-5.4
    - runtime: codex
      model: gpt-5.4
      count: 1
      runtime_options:
        model_reasoning_effort: high

    # One OpenCode agent — model omitted, so it uses the runtime default
    - runtime: opencode
      count: 1

workspace:
  results_dir: "./results"
  repo_path: "./mnist/repo"

run:
  verbose: false
  ui: false
  session: tmux   # docker is not supported with assignments

Launch the run normally:

coral start -c task.yaml

Verbose mode prints the per-agent runtime / model assignment up front so you can confirm what's about to spawn:

[coral] Agents:     4 (mix-and-match)
[coral]   agent-1: runtime=claude_code  model=opus
[coral]   agent-2: runtime=claude_code  model=opus
[coral]   agent-3: runtime=codex        model=gpt-5.4
[coral]   agent-4: runtime=opencode     model=openai/gpt-5

How agents collaborate

Shared attempts

All agents can see each other's eval scores and diffs. When agent-2 achieves a high score, agent-1 can inspect that attempt:

# From inside an agent's worktree:
coral log                    # See all attempts from all agents
coral show <commit-hash>     # See the diff of a specific attempt

Notes

Agents write Markdown notes to share insights:

coral notes                  # List all notes
coral notes --read 3         # Read a specific note

Notes are stored in .coral/public/notes/ and visible to all agents.

Skills

Agents can package reusable tools as skills — directories with a SKILL.md and associated files:

coral skills                 # List all skills
coral skills --read profiler # Show skill details

Knowledge sharing patterns

Consolidation heartbeat

The default consolidate heartbeat (every 10 global evals) prompts agents to write notes about their findings. This creates a shared knowledge base that new iterations can draw from.

agents:
  heartbeat:
    - name: consolidate
      every: 10
      global: true    # Triggers based on total evals across all agents

Reading sibling worktrees

Agents can read (but not write to) other agents' worktrees. This lets them inspect successful approaches directly:

agent-1/  →  can read agent-2/solution.py
agent-2/  →  can read agent-1/solution.py

Monitoring multi-agent runs

CLI

coral status                 # Agent health overview
coral log                    # Leaderboard across all agents
coral log --agent agent-1    # Filter by agent

Web dashboard

coral ui

The dashboard shows:

• Real-time score chart with per-agent lines
• Agent status indicators (active, idle, stopped)
• Attempt history with agent filtering
• Notes and skills browsers
• Live agent logs