/coral-quickstart

name: coral-quickstart
description: The fast path from zero to a running CORAL experiment — what CORAL is and when to reach for it, installing the `coral` CLI, registering a runtime with `coral setup`, and the `.coral_workspace/` convention for pointing CORAL at code you already have and want optimized. Use this whenever the user asks "what is coral", "should I use coral for this", wants to install or get coral set up, hits a "command not found" for coral or doesn't have it installed yet, or says "use coral to optimize / speed up / improve this code" and you need the end-to-end onboarding from install to a launched run. Hands off to `setting-up-coral` (runtime bindings), `creating-a-coral-task` (grader authoring), and `running-coral-experiments` (operating a run) for depth.

CORAL quickstart

**CORAL** is infrastructure for autonomous coding agents: you give it a codebase (`seed/`) and a grader (turns a commit into a number), and it spawns agents in isolated git worktrees that edit code, submit commits, and get scored on a shared leaderboard — looping to push the score up. The agents *are* the optimizer; your grader defines "better".

When to reach for CORAL

**Good fit:**

• You can express success as a **number** — accuracy, runtime ratio, pass rate, or a rubric-judge score for open-ended work.
• The work is **iterative search**: many attempts at one well-scoped problem (kernel/algorithm optimization, benchmark solving, prompt/program tuning, "make this function faster").
• You want **parallel agents** exploring independently and sharing what works.

**Not a fit:**

• One-shot tasks with no measurable objective.
• Work that needs a human judging every attempt (use a rubric-judge grader if a *model* can score it).

How a run is shaped

you provide:   seed/ (starter code)  +  a grader (commit → number)
coral spawns:  N agents, each in its own git worktree
each agent:    edit code → `coral eval` → grader scores it → read leaderboard → repeat
shared state:  attempts, notes, and skills are visible across agents in real time

Two things you build (`seed/` + grader) and one thing you tune (how many agents, which model). Worktrees, scoring daemon, shared state, and restarts are handled for you.

Get running — four steps

1. Install the CLI

curl -fsSL https://raw.githubusercontent.com/Human-Agent-Society/CORAL/main/install.sh | sh
# or, if you have uv:
uv tool install git+https://github.com/Human-Agent-Society/CORAL.git
coral --help      # verify

The installer grabs the **latest `coral` release** by default — that's what you want. (Only pin a specific release with `CORAL_VERSION=<tag>` before the curl if you have a reason to.)

2. Register a runtime (`coral setup`)

`coral` shells out to a coding-agent CLI (Claude Code, Codex, Cursor, Kiro, OpenCode) — each installed and authenticated separately. Tell coral which to use:

coral setup            # scans PATH, wizard to create named runtime bindings
coral agents doctor    # validates them, incl. a live auth ping

If `doctor`'s live ping fails (expired auth, model typo, "runtime not found" at start) → the `setting-up-coral` skill has the full troubleshooting matrix.

3. Build a task — use a `.coral_workspace/`

When the user wants CORAL to optimize **code they already have**, keep every bit of CORAL scaffolding (task config, seed, grader, results) inside a `.coral_workspace/` directory at the root of their project. This keeps coral out of their actual source tree and is trivially gitignored.

> **Act — never answer "optimize this" with a menu.** A request like "use coral to optimize this" (in any language) is a build instruction, not a question. The failure mode to avoid is a process menu like *"1. point me to a task 2. create one 3. optimize outside coral"* — **do not produce that.** A repo with no `task.yaml` isn't ambiguous; it just means you build the task from the current repo. So: > 1. **Dig for what's already measurable.** Research/framework repos (like SAGA) almost always ship an eval/benchmark script, a test suite, or a headline metric in the README/paper. Find it — that's your optimization target and metric. > 2. **If no single number is obvious, construct one** by wrapping the repo's existing evaluation. Don't give up and ask just because there's no CORAL scaffold. > 3. **Scaffold the most plausible target and start building** — a `.coral_workspace/` + draft grader is cheap and reversible. State your assumption in one line ("Optimizing SAGA's <metric> from <script> — building it now; redirect me if you meant something else") and proceed. > 4. **Last resort only:** if you've actually read the repo and it exposes nothing scorable, propose 2-3 **concrete** targets you found (each with a metric), pick the most likely, and scaffold it — still not a process menu. > > Stop before `coral start` (a paid run); everything up to a validated task is autonomous. On Claude Code, delegate this whole grind to the `coral-task-author` subagent.

The mechanical boilerplate (gitignore + `coral init` + copy the code into `seed/`) is bundled as a script — run it from the project root:

"${CLAUDE_PLUGIN_ROOT}/skills/coral-quickstart/scripts/new-coral-workspace.sh" optimize path/to/their_module.py

It scaffolds `.coral_workspace/optimize/` and copies the file into `seed/solution.py`, leaving only the grader for you to write. (Equivalent by hand:)

# from the user's project root
echo ".coral_workspace/" >> .gitignore
mkdir -p .coral_workspace && cd .coral_workspace
coral init optimize && cd optimize
cp ../../path/to/their_module.py seed/solution.py   # the code to optimize

Then make the task fit the user's goal — two edits:

• **`task.yaml`** → set `task.description` to what the agents should optimize and the program file's contract (e.g. "`solution.py` must define `run()` and stay correct; we score speedup").
• **the grader** → score the user's actual metric (speedup vs bas