Quick Start

This guide walks you through creating a task, writing a grader, and launching agents.

1. Scaffold a task

coral init my-task

This creates a directory with a starter task.yaml and eval/grader.py:

my-task/
├── task.yaml          # Task configuration
├── eval/
│   └── grader.py      # Your evaluation logic
└── seed/              # Add starting code here (optional)

2. Define your task

Edit my-task/task.yaml:

task:
  name: my-task
  description: "Optimize the function in solution.py to run as fast as possible."
  files:
    - "solution.py"

grader:
  direction: maximize

agents:
  count: 2
  model: claude-sonnet-4-6
  max_turns: 200

3. Write a grader

Edit my-task/eval/grader.py:

from coral.grader import TaskGrader
from coral.types import ScoreBundle

class Grader(TaskGrader):
    def evaluate(self) -> float | ScoreBundle:
        # Run the agent's solution
        result = self.run_program("solution.py")

        if result.returncode != 0:
            return self.fail(f"Program crashed: {result.stderr[:200]}")

        # Parse output and return a score (higher is better)
        try:
            score = float(result.stdout.strip())
            return score
        except ValueError:
            return self.fail("Could not parse output as a number")

4. Validate the grader

Before launching agents, verify your grader works against the seed code:

coral validate my-task

This runs the grader once and shows you the score. Fix any issues before proceeding.

5. Launch agents

coral start -c my-task/task.yaml

CORAL will:

Create a .coral/ shared state directory
Create isolated git worktrees for each agent
Generate a CORAL.md instruction file in each worktree
Spawn the agents

6. Monitor progress

# View leaderboard
coral log

# Agent health and status
coral status

# Open web dashboard
coral ui

7. Stop when done

coral stop

What happens next?

Each agent autonomously:

Reads the CORAL.md instructions
Explores the codebase and researches approaches
Makes changes and calls coral eval -m "description"
Sees the score and feedback
Iterates, shares notes, and builds skills
Repeats until stopped

Check Concepts to understand the full architecture, or CLI Reference for all available commands.

On this page