CORAL Autonomous Research Infrastructure
Run parallel coding-agent experiments, share discoveries, and continuously score candidate improvements.
Per-dimension scores and reasoning
Evidence: README mentions Docker session isolates agent from grader, agents run as unprivileged user, and cannot read .coral/private/ (grader venv, answer keys), indicating least privilege (least_privilege=2). User confirmation: plugin workflow requires user to explicitly request optimization, but not every action requires confirmation (user_confirmation=1). Data flow transparency: README describes separation of .coral/public/ and .coral/private/, but not detailed data flow (data_flow_transparency=2). Sensitive data handling: isolation of .coral/private/ suggests handling, but no encryption or specific measures (sensitive_data_handling=2). Dependency security: pyproject.toml lists dependencies, but no vulnerability scanning or lock file (dependency_security=1). External effects: agents run in git worktrees, may modify filesystem, but no explicit restrictions (external_effects=2). Rollback: no rollback mechanism mentioned (rollback=1). Source attribution: README cites paper and acknowledgements, but not code provenance (source_attribution=2).
Evidence: README and pyproject.toml are consistent, tests exist, indicating some consistency (self_consistency=2). Dependency availability: dependencies listed, but no lock file or version ranges, may affect reproducibility (dependency_availability=1). Failure messages: README mentions coral-run-doctor for troubleshooting, but no specific failure message examples (failure_messages=1).
Evidence: README describes multiple use cases (optimization, math, systems), audience clear (audience_and_scenarios=2). Capability boundaries: README mentions supported agents and Docker requirement, but not explicit limits (capability_boundaries=2). Trigger precision: plugin workflow has clear steps (coral setup → init/validate → start), but not detailed trigger conditions (trigger_precision=2). Environment fit: README mentions Python 3.11+ and Docker, but not other environments (environment_fit=2).
Evidence: README structure clear, with installation, usage, examples sections (information_architecture=2). Install notes: provides curl command and docs link (install_notes=2). Naming stability: project name and CLI command consistent (naming_stability=2). Examples and FAQ: provides multiple examples, but no FAQ (examples_and_faq=2). Known limitations: README mentions Docker-in-Docker not supported, but not other limitations (known_limitations=2). License: Apache-2.0 license file complete (license=3). Versioning and changelog: README has news updates, but no formal changelog (versioning_changelog=2). Maintenance responsibility: README has contributing guide, but no explicit maintainers (maintenance_responsibility=2).
Evidence: Output usability: README describes outputs (e.g., optimized code), but not specific format (output_usability=2). Marginal value: CORAL provides multi-agent collaboration and automated evaluation, unique value (marginal_value=2). Cost-benefit: README mentions API credits support, but no cost analysis (cost_benefit=2).
Evidence: Claim traceability: README cites paper and blog, but no specific evidence (claim_traceability=2). Cross-source corroboration: paper and blog may provide additional info, but not verified in repo (cross_source_corroboration=1). Fact-inference separation: README distinguishes news and features, but not explicitly (fact_inference_separation=2).
- Dependencies are not locked, which may affect reproducibility.
- No rollback mechanism provided, agents may cause irreversible changes.
- No specific failure message examples, troubleshooting may be difficult.
- No FAQ provided, users may lack answers to common questions.
- No explicit maintainers, long-term maintenance responsibility unclear.
What does this agent do, and when should you use it?
CORAL is multi-agent experimentation infrastructure for autoresearch and open-ended code optimization. Its CLI launches Claude Code, Codex, Cursor Agent, Kiro, or OpenCode, placing every agent in an isolated Git worktree. Agents share attempts, notes, and skills in real time through `.coral/public/`, while a grader daemon scores every commit. The manager can issue `reflect`, `consolidate`, and `pivot` heartbeat prompts, and the system also supports isolated islands, migration, and reusable LLM rubric judges. CORAL runs primarily on the host; when a grader depends on Harbor and Docker, CORAL itself cannot run inside Docker because Docker-in-Docker is unsupported.
Given a codebase, task configuration, and grader, CORAL starts an experiment with coral start -c task.yaml. Its manager creates a separate Git worktree for each coding agent and links .coral/public/ into every workspace so agents can inspect shared attempts, notes, and skills. Agents modify the code and commit candidates, and the grader daemon scores each commit. Heartbeat prompts direct agents to reflect, consolidate knowledge, or pivot, while multi-island runs can scope research state and migrate discoveries between islands. The resulting artifacts are auditable code commits, evaluation scores, and persistent shared research state—not a hosted chat application or a standalone model API.
- An algorithms researcher with an existing codebase and quantitative objective can run parallel searches for better solutions, such as circle packing or conjecture-solving experiments.
- A systems team can repeatedly optimize VLIW SIMD or GPU kernels while having an independent grader evaluate every candidate commit.
- An ML researcher can organize reproducible multi-agent experiments around tasks such as MNIST, Spaceship Titanic, or mRNA degradation prediction.
- A benchmark maintainer can operate SWE-bench or terminal-bench evaluation workflows that use Harbor and Docker isolation.
- A team evaluating open-ended reports, memos, or legal analyses can use the supplied reusable rubric-judge grader packages.
What are this agent's strengths and limitations?
- Native runtimes are documented for Claude Code, Codex, Cursor Agent, Kiro, and OpenCode, allowing teams to change coding-agent harnesses within one experiment framework.
- Separate Git worktrees isolate code changes while
.coral/public/provides real-time knowledge sharing across agents. - The grader daemon ties every score to a commit, producing an inspectable trail of candidate implementations and evaluations.
- Multi-island runs isolate research state and support migration, providing a concrete mechanism for broader, more diverse exploration.
- In Docker sessions, agents run as unprivileged users and cannot access grader environments or answer material stored in
.coral/private/.
- Adoption requires a dependable grader to be designed and packaged; a codebase without a measurable evaluation procedure is insufficient for CORAL's core loop.
- Every coding-agent runtime must be installed and authenticated separately, and CORAL does not bundle the associated accounts, model access, or usage charges.
- Harbor-based graders require Docker, but CORAL cannot itself run in Docker for those tasks because Docker-in-Docker is unsupported.
- Host-side user isolation is opt-in through
agents.isolate_user, so it does not automatically provide the same boundary documented for Docker sessions. - The supplied material lists examples but provides no quantitative throughput, resource-consumption, or comparative benchmark results; teams must validate operating cost at their own scale.
How do you install or deploy this agent?
Prepare Python 3.11+ and separately install and authenticate at least one supported coding agent. Run:
curl -fsSL https://raw.githubusercontent.com/Human-Agent-Society/CORAL/main/install.sh | shThe script installs the latest global coral release through uv tool install. Set CORAL_VERSION=<tag> when a pinned release is required. Graders based on Harbor, including some SWE-bench and terminal-bench setups, also require Docker on the host.
How do you use this agent?
Create and launch a first task with:
coral init my-task
cd my-task && coral start -c task.yamlThe task needs code for the agents to modify and a valid grader configuration. Graders must now be packaged and referenced through grader.entrypoint; legacy eval/grader.py auto-discovery has been removed. For Claude Code, the optional plugin commands are /plugin marketplace add Human-Agent-Society/CORAL followed by /plugin install coral@coral-marketplace. For Codex v0.117.0+, use codex plugin marketplace add Human-Agent-Society/CORAL and codex plugin add coral@coral-marketplace. The plugin uses skills rather than MCP and teaches the setup, init, validate, start, status, and log workflows.
FAQ
Does CORAL include model or coding-agent access?
Can agents read private grader data or answer keys?
.coral/private/. Equivalent host isolation is optional through agents.isolate_user.Can CORAL itself be deployed inside Docker?
Does the Claude Code or Codex plugin require an MCP server?
Will an older task using eval/grader.py still work unchanged?
grader.entrypoint.