Skip to content
Back to search

CORAL

Open-source autoresearch powered by autonomous coding agents. Run Claude Code, OpenCode, and Codex with grading, shared knowledge, and multi-agent evolution. Accepted at COLM 2026.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/human-agent-society--coral/badge.svg)](/listings/human-agent-society--coral)

HTML

<a href="/listings/human-agent-society--coral"><img src="/api/listings/human-agent-society--coral/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

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](https://coral.compounding-intelligence.ai/docs/getting-started/installation) for manual install, dev setup, and prerequisites.

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 19 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "coral-marketplace",
  3. "owner": {
  4. "name": "Human-Agent-Society",
  5. "url": "https://github.com/Human-Agent-Society/CORAL"
  6. },
  7. "metadata": {
  8. "description": "CORAL — multi-agent autonomous coding infrastructure. A skills-first plugin for authoring and running CORAL tasks from your own harness.",
  9. "version": "0.1.0"
  10. },
  11. "plugins": [
  12. {
  13. "name": "coral",
  14. "source": "./plugin",
  15. "description": "Author and run CORAL tasks (init/validate, start/status/resume/log/show) from Claude Code or Codex. Skills + a SessionStart install check.",
  16. "keywords": ["coral", "agents", "evaluation", "benchmarks", "orchestration"]
  17. }
  18. ]
  19. }
README.md · README · 179 lines · 1 finding marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. <img src="assets/logo.png" alt="CORAL logo — multi-agent autonomous coding infrastructure" width="360">
  3. # CORAL: Open-Source Autoresearch Powered by Autonomous Coding Agents
  4. **Robust, lightweight infrastructure for multi-agent self-evolution, built for autoresearch.**
  5. [![Paper](https://img.shields.io/badge/Paper-arXiv%3A2604.01658-B31B1B.svg?logo=arxiv&logoColor=white)](https://arxiv.org/abs/2604.01658v1)
  6. [![Blog](https://img.shields.io/badge/Blog-CORAL-FF6B6B.svg?logo=hashnode&logoColor=white)](https://coral.compounding-intelligence.ai/blogs/)
  7. [![Apache 2.0 License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
  8. [![Python 3.11+](https://img.shields.io/badge/Python-3.11%2B-3776AB.svg?logo=python&logoColor=white)](https://python.org)
  9. **English** | [中文](README_CN.md)
  10. </div>
  11. <p align="center">
  12. <a href="#installation">Installation</a> · <a href="#plugin-drive-coral-from-your-own-agent">Plugin</a> · <a href="#supported-agents">Supported Agents</a> · <a href="#how-it-works">How It Works</a> · <a href="#examples">Examples</a> · <a href="https://coral.compounding-intelligence.ai/docs/">Docs</a> · <a href="https://arxiv.org/abs/2604.01658v1">Paper</a>
  13. </p>
  14. **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.
  15. ### 🔥 News
  16. - **[2026-07-08]** **CORAL** has been accepted to **COLM 2026**! 🎉
  17. - **[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`.
  18. - **[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](https://coral.compounding-intelligence.ai/docs/guides/custom-grader).
  19. - **[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.
  20. - **[2026-04-24]** Rubric judges — two reusable LLM-judge grader packages for open-ended tasks (reports, memos, legal analysis). See the [Rubric Judges guide](https://coral.compounding-intelligence.ai/docs/guides/rubric-judge).
  21. - **[2026-04-03]** Our paper, "CORAL: Towards Autonomous Multi-Agent Evolution for Open-Ended Discovery," is now out! Check it out on [Arxiv](https://arxiv.org/abs/2604.01658v1).
  22. - **[2026-03-18]** CORAL is released! Check out our [blog post](https://coral.compounding-intelligence.ai/blogs/evolve-like-coral/).
  23. ![CORAL demo — autonomous AI coding agents running in parallel git worktrees, sharing knowledge through a common state directory](assets/demo.gif)
  24. ### Installation
  25. ```bash
  26. curl -fsSL https://raw.githubusercontent.com/Human-Agent-Society/CORAL/main/install.sh | sh
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 40 on GitHub
  27. ```
  28. 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](https://coral.compounding-intelligence.ai/docs/getting-started/installation) for manual install, dev setup, and prerequisites.
  29. ```bash
  30. coral init my-task # scaffold a task
  31. cd my-task && coral start -c task.yaml # launch agents
  32. ```
  33. ### Plugin: drive CORAL from your own agent
  34. 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.
  35. **Claude Code:**
  36. ```
  37. /plugin marketplace add Human-Agent-Society/CORAL
  38. /plugin install coral@coral-marketplace
  39. ```
  40. **Codex** (v0.117.0+):
  41. ```
  42. codex plugin marketplace add Human-Agent-Society/CORAL
  43. codex plugin add coral@coral-marketplace
  44. ```
  45. Both pull from this repo's marketplace manifests; the plugin lives under [`plugin/`](plugin/).
  46. **Quickstart — point CORAL at code you already have.** Once installed, open the repo whose code you want to optimize and just ask:
  47. ```
  48. use coral to optimize this — make sample() in saga/decode.py faster without changing its output
  49. ```
  50. 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.
  51. 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](https://coral.compounding-intelligence.ai/docs/guides/plugin) or [`plugin/README.md`](plugin/README.md) for agents, the skills-dir alternative, and other harnesses.
  52. ### Supported Agents
  53. | Agent | `agents.runtime` |
  54. |-------|------------------|
  55. | [Claude Code](https://github.com/anthropics/claude-code) — default | `claude_code` |
  56. | [Codex](https://github.com/openai/codex) | `codex` |
  57. | [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) | `dsh` |
  58. | [Cursor Agent](https://cursor.com/docs/cli/overview) | `cursor` |
  59. | [Kiro](https://kiro.dev) | `kiro` |
  60. | [OpenCode](https://github.com/opencode-ai/opencode) | `opencode` |
  61. | [Pi](https://pi.dev) | `pi` |
  62. Each agent must be installed and authenticated separately. Per-runtime config — including the [LiteLLM gateway](https://coral.compounding-intelligence.ai/docs/guides/gateway) for custom models — is documented at [Agent Runtimes](https://coral.compounding-intelligence.ai/docs/guides/agent-runtimes).
  63. ### How It Works
  64. <p align="center">
  65. <img src="assets/coral_diagram_trans.jpg" alt="CORAL architecture diagram: multiple coding agents run in isolated git worktrees, share state via .coral/public/, and are scored by a grader daemon" width="800">
  66. </p>
  67. 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`).
  68. Deeper dive: [Concepts](https://coral.compounding-intelligence.ai/docs/concepts) · [Multi-agent runs](https://coral.compounding-intelligence.ai/docs/guides/multi-agent) · [Eval loop](https://coral.compounding-intelligence.ai/docs/concepts/eval-loop)
  69. ### Examples
  70. Ready-to-run task configurations in `examples/`:
  71. | Task | Domain | Description |
  72. | -------------------------- | ------------ | ----------------------------------------------------------- |
  73. | **circle_packing** | Optimization | Pack 26 circles into a unit square to maximize sum of radii |
  74. | **erdos** | Mathematics | Solve a math conjecture |
  75. | **kernel_builder** | Systems | VLIW SIMD kernel optimization |
  76. | **kernel_engineering** | Systems | GPU kernel optimization |
  77. | **mnist** | ML | Handwritten digit classification |
  78. | **spaceship_titanic** | ML | Kaggle competition |
  79. | **stanford_covid_vaccine** | Bio/ML | mRNA degradation prediction |
  80. Full catalogue and walkthroughs at [Examples docs](https://coral.compounding-intelligence.ai/docs/examples).
  81. ### Development
  82. ```bash
  83. # Install dev dependencies
  84. uv sync --extra dev
  85. # Run tests
  86. uv run pytest tests/ -v
  87. # Lint & format
  88. uv run ruff check .
  89. uv run ruff format .
  90. ```
  91. > [!IMPORTANT]
  92. > **Docker requirement:** Some built-in graders (e.g. SWE-bench, terminal-bench) use [Harbor](https://github.com/corca-ai/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.
  93. ### Contributing
  94. Contributions are welcome — bug reports, new tasks under `examples/`, new agent runtimes, docs, the lot. Start here:
  95. - [CONTRIBUTING.md](CONTRIBUTING.md) — dev setup, branch & commit conventions, PR workflow, test/lint commands.
  96. - [AGENTS.md](AGENTS.md) — rules for AI-assisted contributions (CORAL is itself agent infrastructure, so we expect agent-authored PRs and have a few specific asks).
  97. For a deeper dive into the codebase, the architecture notes in [CLAUDE.md](CLAUDE.md) cover the eval loop, `.coral/{public,private}/` split, grader daemon, and runtime registry.
  98. This project is released under the Apache 2.0 [LICENSE](LICENSE).
  99. ### Citation
  100. ⭐ If you find CORAL useful, please consider giving us a Star and/or [citing it](https://arxiv.org/abs/2604.01658) in your work (Please use the official BibTeX below instead of Google Scholar’s auto-generated citation, which may truncate the author list):
  101. ```bibtex
  102. @inproceedings{qu2026coral,
  103. title={CORAL: Towards Autonomous Multi-Agent Evolution for Open-Ended Discovery},
  104. 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},
  105. booktitle={Conference on Language Modeling (COLM)},
  106. year={2026}
  107. }
  108. ```
  109. ### Contact Us
  110. - For technical questions and feature requests, please use [GitHub Issues](https://github.com/Human-Agent-Society/CORAL/issues).
  111. - For collaboration and partnerships, please contact [info@compounding-intelligence.ai](mailto:info@compounding-intelligence.ai).
  112. <!-- ## Star History
  113. <a href="https://www.star-history.com/?repos=Human-Agent-Society%2FCORAL&type=date&legend=top-left">
  114. <picture>
  115. <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=Human-Agent-Society/CORAL&type=date&theme=dark&legend=top-left&sealed_token=_Mr1XWVeoHdhN5RB0i4Fz-C0qC_ci1us7BViejAd73QFLQB7w_FW2o-3uWeM_nqAmLucjkLC8pNTEHRR1MVZ7LKGHYmhes0XBWUMTHuAWyJUJeYjB5XCNw" />
  116. <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=Human-Agent-Society/CORAL&type=date&legend=top-left&sealed_token=_Mr1XWVeoHdhN5RB0i4Fz-C0qC_ci1us7BViejAd73QFLQB7w_FW2o-3uWeM_nqAmLucjkLC8pNTEHRR1MVZ7LKGHYmhes0XBWUMTHuAWyJUJeYjB5XCNw" />
  117. <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=Human-Agent-Society/CORAL&type=date&legend=top-left&sealed_token=_Mr1XWVeoHdhN5RB0i4Fz-C0qC_ci1us7BViejAd73QFLQB7w_FW2o-3uWeM_nqAmLucjkLC8pNTEHRR1MVZ7LKGHYmhes0XBWUMTHuAWyJUJeYjB5XCNw" />
  118. </picture>
  119. </a> -->
  120. ### Acknowledgement
  121. We thank the [TNT Accelerator](https://www.tnt.so/) 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](https://github.com/algorithmicsuperintelligence/openevolve), [autoresearch](https://github.com/karpathy/autoresearch), [TTT Discover](https://arxiv.org/abs/2601.16175), etc., that have led to the ideation of Coral.
plugin/hooks/session-start.py · Bundled script · 91 lines · 1 finding marked
  1. #!/usr/bin/env python3
  2. """CORAL plugin SessionStart hook.
  3. Two jobs, both cheap and dependency-free:
  4. 1. Detect whether the `coral` CLI is installed and reachable on PATH.
  5. 2. Inject a small block of context so the agent knows CORAL is available
  6. and which skill to reach for (authoring vs. running tasks).
  7. Output contract (Claude Code SessionStart hook):
  8. print a JSON object on stdout with
  9. hookSpecificOutput.additionalContext — that string is added to the
  10. session context. We never block the session (exit 0 always).
  11. """
  12. from __future__ import annotations
  13. import json
  14. import shutil
  15. import subprocess
  16. import sys
  17. def _coral_version(coral_path: str) -> str | None:
  18. """Best-effort `coral --version`; None if it doesn't answer quickly."""
  19. for args in (["--version"], ["version"]):
  20. try:
  21. out = subprocess.run(
  22. [coral_path, *args],
  23. capture_output=True,
  24. text=True,
  25. timeout=5,
  26. )
  27. except (subprocess.TimeoutExpired, OSError):
  28. return None
  29. if out.returncode == 0:
  30. return (out.stdout or out.stderr).strip() or None
  31. return None
  32. def _installed_context(version: str | None) -> str:
  33. ver = f" ({version})" if version else ""
  34. return (
  35. f"# CORAL is available\n\n"
  36. f"The `coral` CLI is installed{ver}. CORAL runs autonomous coding agents "
  37. f"against a grader and a leaderboard.\n\n"
  38. f"When the user wants to **author a task** (a `task.yaml` + `seed/` + grader "
  39. f"package), use the `creating-a-coral-task` skill. When they want to **run or "
  40. f"manage experiments** (`coral start / status / resume / log / show / stop`), "
  41. f"use the `running-coral-experiments` skill. For install / what-is-coral / "
  42. f"when-to-use, see `coral-quickstart`.\n\n"
  43. f"Don't memorize flags — run `coral --help` or `coral <cmd> --help`, and let "
  44. f"the skills drive the workflow.\n"
  45. )
  46. def _missing_context() -> str:
  47. return (
  48. "# CORAL CLI not found\n\n"
  49. "The `coral` CLI is not on PATH. If the user asks to author or run a CORAL "
  50. "task, install it first:\n\n"
  51. "```bash\n"
  52. "curl -fsSL https://raw.githubusercontent.com/Human-Agent-Society/CORAL/main/install.sh | sh\n"
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 62 on GitHub
  53. "# or, with uv:\n"
  54. "uv tool install git+https://github.com/Human-Agent-Society/CORAL.git\n"
  55. "```\n\n"
  56. "Then the `creating-a-coral-task` and `running-coral-experiments` skills apply. "
  57. "Docs: https://coral.compounding-intelligence.ai/docs/\n"
  58. )
  59. def main() -> int:
  60. coral_path = shutil.which("coral")
  61. if coral_path:
  62. context = _installed_context(_coral_version(coral_path))
  63. else:
  64. context = _missing_context()
  65. json.dump(
  66. {
  67. "hookSpecificOutput": {
  68. "hookEventName": "SessionStart",
  69. "additionalContext": context,
  70. }
  71. },
  72. sys.stdout,
  73. )
  74. return 0
  75. if __name__ == "__main__":
  76. sys.exit(main())

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.