CORAL

Robust, lightweight infrastructure for multi-agent self-evolution, built for autoresearch.

English | 中文

CORAL is infrastructure for autonomous AI agent organizations that run experiments, share knowledge, and continuously improve solutions. Give it a codebase and a grader, and CORAL handles the rest: isolated workspaces, safe evaluation, persistent shared state, and multi-agent collaboration. Natively integrated with Claude Code, OpenCode, Codex, Cursor Agent, and Kiro.

🔥 News

• [2026-06-24] The Docker session now isolates the agent from the grader: each agent runs as an unprivileged user (manager and grader stay root), so agents can no longer read .coral/private/ (grader venv, answer keys) — not even via Bash. On the host this stays opt-in via agents.isolate_user.
• [2026-06-13] Legacy eval/grader.py grader auto-discovery is deprecated and removed — wire graders via grader.entrypoint pointing at a packaged grader. See the custom grader guide.
• [2026-06-06] CORAL v0.6.0 adds multi-island runs: partition agents into isolated islands with scoped attempts, notes, skills, heartbeat state, and migration between islands for broader exploration.
• [2026-04-24] Rubric judges — two reusable LLM-judge grader packages for open-ended tasks (reports, memos, legal analysis). See the Rubric Judges guide.
• [2026-04-03] Our paper, "CORAL: Towards Autonomous Multi-Agent Evolution for Open-Ended Discovery," is now out! Check it out on Arxiv.
• [2026-03-18] CORAL is released! Check out our blog post.

Installation

curl -fsSL https://raw.githubusercontent.com/Human-Agent-Society/CORAL/main/install.sh | sh

Installs the latest coral release globally via uv tool install. Pin a specific release with CORAL_VERSION=<tag> if you need to. See Installation docs for manual install, dev setup, and prerequisites.

coral init my-task                       # scaffold a task
cd my-task && coral start -c task.yaml   # launch agents

Plugin: drive CORAL from your own agent

Prefer to author and run CORAL tasks from inside your own Claude Code or Codex without memorizing the CLI? Install the CORAL plugin — a skills-first bundle (no MCP) that teaches the workflows (coral setup → init/validate → start/status/log) and checks coral is installed on session start.

Claude Code:

/plugin marketplace add Human-Agent-Society/CORAL
/plugin install coral@coral-marketplace

Codex (v0.117.0+):

codex plugin marketplace add Human-Agent-Society/CORAL
codex plugin add coral@coral-marketplace

Both pull from this repo's marketplace manifests; the plugin lives under plugin/.

Quickstart — point CORAL at code you already have. Once installed, open the repo whose code you want to optimize and just ask:

use coral to optimize this — make sample() in saga/decode.py faster without changing its output

The plugin scaffolds a gitignored .coral_workspace/, drops your code into a seed/, writes a grader for your metric, and loops coral validate until the task is launch-ready — then hands you the coral start command. On Claude Code a coral-task-author subagent does the whole grind autonomously (and a coral-run-doctor triages a stuck run); on any harness the bundled skills walk the same path.

Skills: coral-quickstart (install → setup → .coral_workspace/), setting-up-coral (runtime bindings), creating-a-coral-task (grader authoring), running-coral-experiments (operate a run). See the Harness Plugin guide or plugin/README.md for agents, the skills-dir alternative, and other harnesses.

Supported Agents

Each agent must be installed and authenticated separately. Per-runtime config — including the LiteLLM gateway for custom models — is documented at Agent Runtimes.

How It Works

Each agent runs in its own git worktree. Shared state (attempts, notes, skills) lives in .coral/public/ and is symlinked into every worktree — agents see each other's work in real time. A grader daemon scores every commit. The manager interrupts agents with heartbeat prompts (reflect, consolidate, pivot).

Deeper dive: Concepts · Multi-agent runs · Eval loop

Examples

Ready-to-run task configurations in examples/:

Full catalogue and walkthroughs at Examples docs.

Development

# Install dev dependencies
uv sync --extra dev

# Run tests
uv run pytest tests/ -v

# Lint & format
uv run ruff check .
uv run ruff format .

[!IMPORTANT] Docker requirement: Some built-in graders (e.g. SWE-bench, terminal-bench) use Harbor to run evaluations inside Docker containers. CORAL itself must not run inside Docker in this case, as Docker-in-Docker (DinD) is not supported. Run CORAL directly on the host machine.

Contributing

Contributions are welcome — bug reports, new tasks under examples/, new agent runtimes, docs, the lot. Start here:

• CONTRIBUTING.md — dev setup, branch & commit conventions, PR workflow, test/lint commands.
• AGENTS.md — rules for AI-assisted contributions (CORAL is itself agent infrastructure, so we expect agent-authored PRs and have a few specific asks).

For a deeper dive into the codebase, the architecture notes in CLAUDE.md cover the eval loop, .coral/{public,private}/ split, grader daemon, and runtime registry.

This project is released under the Apache 2.0 LICENSE.

Citation

⭐ If you find CORAL useful, please consider giving us a Star and/or citing it in your work (Please use the official BibTeX below instead of Google Scholar’s auto-generated citation, which may truncate the author list):

@article{qu2026coral,
  title={CORAL: Towards Autonomous Multi-Agent Evolution for Open-Ended Discovery},
  author={Qu, Ao and Zheng, Han and Zhou, Zijian and Yan, Yihao and Tang, Yihong and Ong, Shao Yong and Hong, Fenglu and Zhou, Kaichen and Jiang, Chonghe and Kong, Minwei and Zhu, Jiacheng and Jiang, Xuan and Li, Sirui and Wu, Cathy and Low, Bryan Kian Hsiang and Zhao, Jinhua and Liang, Paul Pu},
  journal={arXiv preprint arXiv:2604.01658},
  year={2026}
}