---
title: Multi-Agent Runs
description: Run multiple agents in parallel with knowledge sharing.
---


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

## Configuration

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

Or override at launch:

```bash
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`:

```yaml
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.

```yaml
agents:
  count: 4

islands:
  count: 2
```

Or override at launch:

```bash
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:

```bash
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.

```yaml
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:

```yaml
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:

```bash
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:

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

```bash
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:

```bash
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.

```yaml
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

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

### Web dashboard

```bash
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
