Configuration

Every CORAL task is defined by a task.yaml file. This page documents all available options.

Full example

task:
  name: "my-task"
  description: "Optimize solution.py to maximize accuracy."
  tips: "numpy and scipy are available. Timeout is 300s."

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

agents:
  count: 2
  runtime: claude_code
  model: claude-sonnet-4-6
  max_turns: 200
  timeout: 3600
  research: true
  heartbeat:
    - name: reflect
      every: 1
    - name: consolidate
      every: 10
      global: true

sharing:
  attempts: true
  notes: true
  skills: true

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

`task` section

Field	Type	Default	Description
`name`	string	required	Task identifier
`description`	string	required	What agents should do — included in CORAL.md
`tips`	string	`""`	Additional hints shown to agents

`grader` section

Field	Type	Default	Description
`entrypoint`	string	`""`	Setuptools-style `module.path:ClassName`. Recommended. Empty falls back to the deprecated `eval/grader.py` discovery.
`setup`	list[string]	`[]`	Shell commands run inside `.coral/private/grader_venv/` at `coral start` / `coral validate` time (typically `uv pip install -e ./grader`).
`timeout`	int	`300`	Eval timeout in seconds (0 = no limit)
`direction`	string	`"maximize"`	`"maximize"` or `"minimize"` — which direction is better
`private`	list[string]	`[]`	Files copied to `.coral/private/` (hidden from agents)
`args`	dict	`{}`	Extra arguments passed to the grader (accessible as `self.args`)

The legacy grader.type and grader.module fields have been removed. Tasks that still set them fail to load with a migration error pointing at grader.entrypoint.

When grader.entrypoint is set, CORAL bootstraps a venv at .coral/private/grader_venv/, runs every command in grader.setup inside it, and spawns a worker subprocess from that venv whenever an attempt needs grading.

When grader.entrypoint is empty, CORAL falls back to auto-discovering eval/grader.py from the task directory. This still works but emits a DeprecationWarning on load — see Writing a Custom Grader for the migration guide.

`agents` section

Field	Type	Default	Description
`count`	int	`1`	Number of agents to spawn
`runtime`	string	`"claude_code"`	Agent runtime: `claude_code`, `codex`, `opencode`
`model`	string	`"sonnet"`	Model to use (e.g. `opus`, `sonnet`, `haiku`, or full model ID)
`max_turns`	int	`200`	Maximum conversation turns per agent
`timeout`	int	`3600`	Agent session timeout in seconds
`research`	bool	`true`	Enable web search in agent workflow
`heartbeat`	list	see below	Periodic actions triggered during eval loop

Heartbeat actions

Heartbeat actions run at regular intervals based on eval count:

heartbeat:
  - name: reflect        # Built-in: agent reviews progress
    every: 1             # After every eval
  - name: consolidate    # Built-in: agents share knowledge
    every: 10
    global: true         # Uses global eval count (all agents combined)

You can also define custom heartbeat actions with a prompt:

coral heartbeat set review --every 5 --prompt "Review your approach and consider alternatives."

Controls what shared state is enabled in .coral/public/:

Field	Type	Default	Description
`attempts`	bool	`true`	Share attempt scores between agents
`notes`	bool	`true`	Enable shared notes
`skills`	bool	`true`	Enable shared skills

`workspace` section

Field	Type	Default	Description
`results_dir`	string	`"./results"`	Where to store run results
`repo_path`	string	`"."`	Path to the git repository root