---
title: Quick Start
description: Run your first CORAL task in 5 minutes.
---


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

## 1. Scaffold a task

```bash
coral init my-task
```

This creates a self-contained task with a packaged grader:

```
my-task/
├── task.yaml                              # task config + grader entrypoint
├── seed/
│   └── solution.py                        # baseline the agent iterates on
└── grader/                                # standalone Python package
    ├── pyproject.toml                     # name: my-task-grader, deps: [coral]
    └── src/
        └── my_task_grader/
            ├── __init__.py                # re-exports Grader
            └── grader.py                  # class Grader(TaskGrader): ...
```

The grader ships as a real Python package so it gets its own isolated venv at run time (created from `grader.setup` in `task.yaml`). This avoids the legacy `eval/grader.py` in-process load and the `DeprecationWarning` that came with it.

## 2. Define your task

Edit `my-task/task.yaml`:

```yaml
task:
  name: my-task
  description: "Optimize the function in solution.py to print a higher score."

grader:
  entrypoint: "my_task_grader.grader:Grader"
  setup:
    - "uv pip install -e ./grader"
  timeout: 300
  direction: maximize
  args:
    program_file: "solution.py"

agents:
  count: 2
  runtime: claude_code
  model: claude-sonnet-4-6

workspace:
  repo_path: "./seed"
```

## 3. Write a grader

The scaffold already includes a working stub at `my-task/grader/src/my_task_grader/grader.py` that runs `solution.py` and parses a single float from stdout. Customise `evaluate()` for your scoring logic:

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


class Grader(TaskGrader):
    def evaluate(self) -> float | ScoreBundle:
        program_file = self.args.get("program_file", "solution.py")
        result = self.run_program(program_file)

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

        try:
            return float(result.stdout.strip())
        except ValueError:
            return self.fail("Could not parse output as a number")
```

What you have on `self`: `codebase_path` (agent worktree), `private_dir` (`.coral/private/` for hidden answer keys), `args` (dict from `grader.args`), `timeout`, plus helpers `run_program(filename)`, `score(value, explanation=...)`, `fail(reason)`. See the [Custom Grader guide](/guides/custom-grader) for the full API.

If the grader needs extra dependencies (`numpy`, `torch`, etc.), add them to `my-task/grader/pyproject.toml` under `dependencies` — they'll be installed into the grader's venv by `coral validate` and the daemon.

## 4. Validate the grader

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

```bash
coral validate my-task
```

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

## 5. Launch agents

```bash
coral start -c my-task/task.yaml
```

CORAL will:
1. Create a `.coral/` shared state directory
2. Create isolated git worktrees for each agent
3. Generate a `CORAL.md` instruction file in each worktree
4. Spawn the agents

## 6. Monitor progress

```bash
# View leaderboard
coral log

# Agent health and status
coral status

# Open web dashboard
coral ui
```

## 7. Stop when done

```bash
coral stop
```

## What happens next?

Each agent autonomously:
1. Reads the `CORAL.md` instructions
2. Explores the codebase and researches approaches
3. Makes changes and calls `coral eval -m "description"`
4. Sees the score and feedback
5. Iterates, shares notes, and builds skills
6. Repeats until stopped

Check [Concepts](/concepts) to understand the full architecture, or [CLI Reference](/cli/reference) for all available commands.

## Legacy `eval/grader.py` form

Older tasks under `examples/` (and any task you wrote before this release) use a different layout:

```
my-task/
├── task.yaml
├── eval/
│   └── grader.py
└── seed/
```

CORAL still auto-discovers `eval/grader.py` and loads it in-process — it just emits a `DeprecationWarning`. To migrate an existing task to the packaged form, see [Writing a Custom Grader → Migrating from `eval/grader.py`](/guides/custom-grader). New tasks scaffolded by `coral init` use the packaged form by default.
