How do I install coral?

Run these in Claude Code: /plugin marketplace add Human-Agent-Society/CORAL then /plugin install coral@coral-marketplace. Then prompt normally.

Does coral auto-invoke its skills?

Not yet. It is indexed on Flowy as a plain plugin. Request auto-invocation on its page and Flowy will route its skills for you as you prompt.

Yes. Flowy is free and open source, with nothing gated. You can read every skill in full before you install.

Automation

Plugin

coral

Robust, lightweight infrastructure for multi-agent self-evolution, built for autoresearch. CORAL is infrastructure for autonomous AI agent organizations that run experiments, share knowledge, and continuously improve solutions.

FLOW.md

human-agent-society@human-agent-society

GitHub

Plugin Signal84/100Strong

maintained100

capable64

documented100

adopted63

Install on Claude Code

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

Stats

Python Bash Docker Git GitHub

+3 tags

Anthropic OpenAI MCP

880

Stars

118

Forks

Active

Maintenance

Python

Language

Apache-2.0

License

1d ago

Last commit

4mo ago

Created

Repo: Human-Agent-Society/CORAL

What's inside

Skills

/coral-debugVerify and debug changes to CORAL itself — smallest reproduce loop per area (grader / daemon / CLI / hooks / manager / workspace / hub / template / config / web), where to look when something breaks (hung graders, agent restart loops, stalled agents, missing heartbeat actions,/coral-extendAdd a new component to the CORAL framework itself — a new agent runtime under `coral/agent/builtin/` (claude_code/codex/cursor_agent style), a new CLI command in `coral/cli/`, a new bundled skill or subagent template under `coral/template/skills/` or `coral/template/agents/`, a /coral-new-taskEnd-to-end recipe for adding a new task under `examples/` — the three pieces that have to line up (`task.yaml`, `seed/`, and `grader/`), what to put in each, the `TaskGrader` API surface, the `coral validate` → smoke-test loop, and the common mistakes (repo_path pointing at the /promoting-dev-to-mainUse when preparing, reviewing, resolving conflicts for, or merging a CORAL release pull request from the long-lived dev branch into main./create-notesWrite a note to {shared_dir}/notes/ that future agents can actually act on. Use after every coral eval, when a heartbeat (reflect / consolidate / pivot) asks for a note, or when you discover a grader / build / runtime issue that future agents will hit. Covers 4 note variants /deep-researchResearch the problem domain before coding. Web search for techniques, save raw sources, write structured findings, update the index.

Show all 12 skills

/organize-filesOrganize the shared notes directory when it becomes hard to navigate. Restructure within research/ and experiments/, deduplicate, update index.md./skill-creatorAutonomously create, test, and optimize skills by detecting reusable patterns in your own work. Use when you notice repeated tool sequences, recurring code patterns across attempts, or insights that should be captured as a packaged skill. Also use to benchmark and iterate on /coral-quickstartThe 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 /creating-a-coral-taskAuthor a new CORAL task — the three pieces that must line up (`task.yaml`, `seed/`, a packaged `grader/`), the `coral init` → `coral validate` → smoke-test loop, and how to pick a grader pattern (stdout float, test pass-rate, ratio-vs-baseline, multi-metric, or an LLM rubric /running-coral-experimentsRun and manage CORAL experiments from the operator side — launch agents with `coral start` (dotlist overrides, model/count, tmux vs local), monitor with `coral status` / `coral log` / `coral show` / the web dashboard, and drive the loop with `coral resume` (inject instructions,/setting-up-coralOne-time machine setup after installing the `coral` CLI — register local agent runtimes as named bindings with `coral setup` / `coral setup agent`, validate them with `coral agents doctor` (incl. a live hello-ping that catches expired auth and model typos), and reference them

Agents

deep-researcherDeep researcher — spawn to conduct thorough web research on the problem domain, save raw sources, and write structured findings. Use proactively when starting a new task, when scores plateau, or when the team needs fresh ideas from literature.librarianKnowledge librarian — spawn to organize notes, deduplicate findings, and consolidate reusable patterns into skills. Use proactively when the notes directory has grown large, contains duplicates, or is hard to navigate.synthesis-reviewerVerify that every claim in a research note is grounded in its linked raw sources.dedup-judgeDecide what to do with two notes flagged as near-duplicates — without knowing which is which.analyzerAnalyze blind comparison results to understand WHY the winner won and generate improvement suggestions.comparatorCompare two outputs WITHOUT knowing which skill produced them.

Show all 9 agents

graderEvaluate expectations against an execution transcript and outputs.coral-run-doctorUse this subagent to diagnose a CORAL run that's misbehaving — agents restarting, every eval failing, the score plateaued, or "is this run healthy?". It reads `coral status` / `coral log` / `coral show` / notes, identifies the pathology, and returns a ranked set of concrete coral-task-authorUse this subagent to turn "optimize / speed up / improve this with CORAL" into a working CORAL task. Give it the code (or just a repo and a rough goal) and it acts immediately — explores the repo to infer the optimization target, scaffolds a .coral_workspace/, writes the grader,

README

Read on GitHub

CORAL: Open-Source Autoresearch Powered by Autonomous Coding Agents

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-07-08] CORAL has been accepted to COLM 2026! 🎉
[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.

CORAL demo — autonomous AI coding agents running in parallel git worktrees, sharing knowledge through a common state directory

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

Agent	`agents.runtime`
Claude Code — default	`claude_code`
Codex	`codex`
Cursor Agent	`cursor`
Kiro	`kiro`
OpenCode	`opencode`

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/:

Task	Domain	Description
circle_packing	Optimization	Pack 26 circles into a unit square to maximize sum of radii
erdos	Mathematics	Solve a math conjecture
kernel_builder	Systems	VLIW SIMD kernel optimization
kernel_engineering	Systems	GPU kernel optimization
mnist	ML	Handwritten digit classification
spaceship_titanic	ML	Kaggle competition
stanford_covid_vaccine	Bio/ML	mRNA degradation prediction

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}
}

Star History

Acknowledgement

We thank the TNT Accelerator for their generous support of various API credits that have helped during the development of Coral. We would also like to thank many of the inspiring prior works such as OpenEvolve, autoresearch, TTT Discover, etc., that have led to the ideation of Coral.

File tree

1168

Human-Agent-Society/CORALView on GitHub

.agents/
  plugins/
    marketplace.json
.claude/
.claude-plugin/
  marketplace.json
  skills/
    coral-debug/
      SKILL.md
    coral-extend/
      SKILL.md
    coral-new-task/
      SKILL.md
    promoting-dev-to-main/
      agents/
        openai.yaml
      SKILL.md
.dockerignore
.github/
  ISSUE_TEMPLATE/
    bug_report.yml
    config.yml
    feature_request.yml
  PULL_REQUEST_TEMPLATE.md
  release.yml
  scripts/
    tag-promoted-release.sh
  workflows/
    ci.yml
    deploy-blog.yml
    main-pr-source.yml
    promotion-release.yml
    release.yml
.gitignore
.pre-commit-config.yaml
AGENTS.md
assets/
  coral_diagram_trans.jpg
  coral_diagram_white_bg.jpg
  coral_diagram.html
  coral_diagram.png
  coral_logo_transparent.png
  coral_logo.png
  demo.gif
  logo.png
  meta.png
  mit_logo.png
  mit.png
  nus.png
  stanford.png
blog/
  consensus-screenshot.png
  coral_logo.png
  cross_referencing.png
  erdos_comparison_v2.png
  ind_agent_screenshot.png
  index.html
  kernel_builder_comparison.png
  stages.png
  stanford_covid_vaccine_comparison.png
CLAUDE.md
CONTRIBUTING.md
coral/
  __init__.py
  agent/
    __init__.py
    assignments.py
    builtin/
      __init__.py
      claude_code.py
      codex.py
      cursor_agent.py
      kiro.py
      opencode.py
      pi_agent.py
    exit_classifier.py
    heartbeat.py
    manager.py
    migration.py
    nicknames.py
    process.py
    registry.py
    runtime.py
    state.py
    warmstart.py
  cli/
    __init__.py
    __main__.py
    _helpers.py
    agents.py
    author.py
    eval.py
    heartbeat.py
    query.py
    start.py
    ui.py
    validation.py
  config.py
  gateway/
    __init__.py
    config.py
    middleware.py
    server.py
  grader/
    __init__.py
    base.py
    builtin/
      __init__.py
      function_grader.py
    daemon.py
    loader.py
    protocol.py
    subprocess_grader.py
    task_grader.py
  hooks/
    __init__.py
    post_commit.py
  hub/
    __init__.py
    _island.py
    attempts.py
    auto_stop.py
    checkpoint.py
    heartbeat.py
    notes.py
    prompts/
      consolidate.md
      lint_wiki.md
      pivot.md
      reflect.md
      warmstart_research.md
    skills.py
    steering.py
  sandbox/
    __init__.py
    protocol.py
    registry.py
    srt.py
  template/
    __init__.py
    agents/
      deep-researcher.md
      librarian.md
    coral_md.py
    coral_single.md.template
    coral.md.template
    presets/
      docker-opencode.yaml
      local-claude.yaml
      multi-island.yaml
      sandbox.yaml
    role_template.md
    skills/
      create-notes/
        references/
          frontmatter-spec.md
          worked-example.md
        scripts/
          lint.py
          stamp.py
          unattributed.py
        SKILL.md
      deep-research/
        agents/
          synthesis-reviewer.md
        references/
          failure-modes.md
          research-note-template.md
          source-types.md
        scripts/
          check_grounding.py
        SKILL.md
      organize-files/
        agents/
          dedup-judge.md
        references/
          edge-cases.md
          worked-example.md
        scripts/
          audit.sh
          find_duplicates.py
          generate_index.py
          move_note.py
          resolve_links.py
        SKILL.md
      skill-creator/
        agents/
          analyzer.md
          comparator.md
          grader.md
        assets/
          eval_review.html
        eval-viewer/
          generate_review.py
          viewer.html
        LICENSE.txt
        references/
          schemas.md
        SKILL.md
  types.py
  user_agents.py
  web/
    __init__.py
    api.py
    app.py
    events.py
    logs.py
    run_catalog.py
    static/
      assets/
        index-BQi9Jpme.css
        index-CI3RbXHp.js
      index.html
  workspace/
    __init__.py
    breadcrumbs.py
    grader_env.py
    project.py
    repo.py
    user_isolation.py
    worktree.py
demos/
  kernel_builder_1103.py
  solution_erdos.py
docker/
  claude/
    Dockerfile
    entrypoint.sh
  codex/
    Dockerfile
    entrypoint.sh
  opencode/
    Dockerfile
    entrypoint.sh
docs/
  app/
    (site)/
      blogs/
        page.tsx
      layout.tsx
      page.tsx
    api/
      search/
        route.ts
    docs/
      [[...slug]]/
        layout.tsx
        page.tsx
    global.css
    layout.tsx
    opengraph-image.tsx
    robots.ts
    sitemap.ts
  components/
    mdx.tsx
  content/
    docs/
      api/
        config.mdx
        grader.mdx
        hub.mdx
        index.mdx
        meta.json
        types.mdx
      cli/
        index.mdx
        meta.json
        reference.mdx
      concepts/
        agents.mdx
        architecture.mdx
        eval-loop.mdx
        index.mdx
        meta.json
        shared-state.mdx
      examples/
        index.mdx
        meta.json
        tasks.mdx
      getting-started/
        configuration.mdx
        index.mdx
        installation.mdx
        meta.json
        quickstart.mdx
      guides/
        agent-bindings.mdx
        agent-runtimes.mdx
        benchmarks.mdx
        custom-grader.mdx
        gateway.mdx
        index.mdx
        meta.json
        multi-agent.mdx
        plugin.mdx
        rubric-judge.mdx
        web-dashboard.mdx
      index.mdx
      meta.json
      tutorials/
        build-autonomous-agent-grader.mdx
        meta.json
      what-is-coral.mdx
  lib/
    blogs.ts
    layout.shared.tsx
    metadata.ts
    source.ts
  next-env.d.ts
  next.config.mjs
  package-lock.json
  package.json
  postcss.config.mjs
  public/
    coral_logo.png
    llms.txt
  scripts/
    sync-blog.mjs
  source.config.ts
  superpowers/
    plans/
      2026-07-15-unified-coral-site.md
    specs/
      2026-07-15-unified-coral-site-design.md
  tests/
    blog-sync.test.mjs
    canonical-links.test.mjs
    site-routes.test.mjs
  tsconfig.json
examples/
  ADRS/
    cloudcast/
      grader/
        pyproject.toml
        src/
          cloudcast_grader/
            __init__.py
            grader.py
      seed/
        initial_program.py
      task.yaml
      taskdata/
        broadcast.py
        evaluator.py
        examples/
          config/
            inter_agz.json
            inter_gaz2.json
            intra_aws.json
            intra_azure.json
            intra_gcp.json
        profiles/
          cost.csv
          throughput.csv
        simulator.py
        utils.py
    eplb/
      grader/
        pyproject.toml
        src/
          eplb_grader/
            __init__.py
            grader.py
      seed/
        initial_program.py
      task.yaml
      taskdata/
        evaluator.py
    llm_sql/
      grader/
        pyproject.toml
        src/
          llm_sql_grader/
            __init__.py
            grader.py
      seed/
        initial_program.py
      task.yaml
      taskdata/
        evaluator.py
        solver.py
        utils.py
    prism/
      grader/
        pyproject.toml
        src/
          prism_grader/
            __init__.py
            grader.py
      seed/
        initial_program.py
      task.yaml
      taskdata/
        evaluator.py
    txn_scheduling/
      grader/
        pyproject.toml
        src/
          txn_scheduling_grader/
            __init__.py
... 1600 more

Showing a partial view of a very large repo.

FAQ

coral is a Claude Code plugin with 12 hand-picked skills for automation work, indexed on Flowy. Install it with the command on its page. It includes coral-debug, coral-extend, coral-new-task. Its skills do not fire on their own yet. Request auto-invocation to have Flowy route them as you prompt. Free and open source.

What is coral?: Robust, lightweight infrastructure for multi-agent self-evolution, built for autoresearch. CORAL is infrastructure for autonomous AI agent organizations that run experiments, share knowledge, and continuously improve solutions.
How do I install coral?: Run these in Claude Code: /plugin marketplace add Human-Agent-Society/CORAL then /plugin install coral@coral-marketplace. Then prompt normally.
Does coral auto-invoke its skills?: Not yet. It is indexed on Flowy as a plain plugin. Request auto-invocation on its page and Flowy will route its skills for you as you prompt.
Is coral free?: Yes. Flowy is free and open source, with nothing gated. You can read every skill in full before you install.