CORAL CLI
Runs several agents (Claude Code, Codex, OpenCode and others) on one codebase: each in its own git worktree, shared notes, every commit scored by a grader
- 1,105 ★ on the repository
- Last commit
- Apache-2.0
Broad access
Why this level
- It launches several agents that edit code and commit in worktrees without your involvement at each step
- It executes grader code and agent solutions on your machine; outside Docker the isolation of the agent from the grader is off
- Each agent runs under your keys and sign-in, so a long run spends plan limits or API balance
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/coralDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- It launches several agents that edit code and commit in worktrees without your involvement at each step
- It executes grader code and agent solutions on your machine; outside Docker the isolation of the agent from the grader is off
- Each agent runs under your keys and sign-in, so a long run spends plan limits or API balance
This is third-party code. Review the repository files before installing.
What it does
CORAL is Python infrastructure for autonomous research runs. You give it code and a grader, meaning a program that returns a numeric score for a solution, and CORAL launches several agents that try variants in a loop. Each agent works in its own git worktree. Shared state, which is attempts, notes and skills, lives in `.coral/public/` and is symlinked into every tree, so agents see each other's work. A grader daemon scores every commit, and the manager interrupts agents with `reflect`, `consolidate` and `pivot` prompts: think it over, merge what was found and change direction. The CLI installs through a script from the repository using `uv tool install`. `coral init my-task` creates a task scaffold and `coral start -c task.yaml` launches the agents; `coral validate`, `status`, `log`, `show`, `resume` and `stop` are also available. Besides Claude Code, the default, six agents are supported: Codex, DeepSeek Harness, Cursor Agent, Kiro, OpenCode and Pi, each installed and signed in separately. Agents can be split into isolated islands with migration between them, and tasks without a numeric metric get LLM-based rubric graders. Examples live in `examples/`: circle packing, a math conjecture, kernel optimization, MNIST and a Kaggle competition. A separate plugin for Claude Code and Codex teaches an agent to drive CORAL for you. Four skills cover installation, runtime registration, writing a task with a grader and running experiments. In a repository with your code you can just say "use coral to optimize this": the plugin creates a `.coral_workspace/` directory, writes a grader for your metric and loops `coral validate` until the seed solution scores cleanly. In Claude Code the `coral-task-author` subagent does this, and `coral-run-doctor` triages a stuck run.
Who it is for. For researchers and engineers who have a measurable goal for code, such as kernel speed or model accuracy, and a budget for long parallel agent runs.
Good fit when
- You need to speed up a function without changing its output, and speed can be measured: the grader returns a number while agents search for a better variant
- You solve an optimization problem or a Kaggle-style contest and want several agents to try different approaches and share findings in common notes
- You attach different agents to one task, such as Claude Code and Codex, and compare results with a grader instead of by eye
- The task is open-ended, like a report or a legal analysis: a rubric-based LLM grader stands in for a numeric metric
- You want a plugin so that Claude Code or Codex sets up the task, writes the grader and runs `coral start` itself
Not a fit when
- The task has no metric or check that a grader program can express: without one CORAL has nothing to optimize
- You need a one-off fix or refactor by one agent: running several agents with a grader is overkill for that
- Your Python is older than 3.11 or newer than 3.13: the package declares support only for 3.11 through 3.13
- You want to run CORAL inside Docker together with SWE-bench or terminal-bench graders: nested Docker is not supported, so run CORAL on the machine itself
Example request
Use coral to make sample() in saga/decode.py faster without changing its output, and show me the command to launch itLimitations
- The project is alpha by its package classifier, and version 0.6.0 added islands and migration between them. The old `eval/grader.py` grader discovery was removed: a grader is wired through `grader.entrypoint` pointing at a grader package.
- Each agent is installed and authorized separately: CORAL does not supply keys of its own. A LiteLLM gateway handles models outside the native channels, with the `litellm[proxy]` version pinned in the dependencies.
- Isolation of the agent from the grader is on in Docker: the agent runs as an unprivileged user and cannot read `.coral/private/` with the answers. Outside Docker it is switched on manually with `agents.isolate_user`.
- Harbor graders run their checks in Docker containers, so CORAL itself cannot run in Docker in that case.
- The paper on CORAL was accepted at COLM 2026, and the result examples in the blog come from the authors' own tasks, so a repeat on your code is not guaranteed.
How to disable. Stop a run with `coral stop`. A package installed through `uv tool install` is removed with `uv tool uninstall coral`. Remove the plugin with the same plugin manager you installed it with; its name is `coral@coral-marketplace`. Worktrees and the `.coral` directory remain in the project and are deleted by hand.
FAQ
What is a grader and why is it needed?
It is a package that takes an agent's solution and returns a numeric score. The grader daemon runs it on every commit. These scores tell agents whether the work is moving forward, and the manager uses them to decide when to interrupt with a prompt.
Which prompts does the manager send to agents?
Three: `reflect` asks to think over what is done, `consolidate` to merge findings into notes, `pivot` to change direction. The texts live in `coral/hub/prompts` and fire on a heartbeat timer.
How do islands differ from a plain run?
Since version 0.6.0 agents are split into isolated islands, each with its own attempts, notes, skills and heartbeat state. Solutions can migrate between islands, which widens the search.
Which skills and subagents does the plugin install?
The skills `coral-quickstart`, `setting-up-coral`, `creating-a-coral-task` and `running-coral-experiments`. The subagents `coral-task-author` and `coral-run-doctor` work only in Claude Code. On session start a hook checks that `coral` is on PATH.
Which Codex version does the plugin need?
Codex 0.117.0 or newer, which has plugins installed from a repository. Install with `codex plugin marketplace add Human-Agent-Society/CORAL` and `codex plugin add coral@coral-marketplace`. Skills are invoked through `$coral-quickstart` or by description.
Discussion
No questions or reviews yet.
Related
CLI toolsMulti-agent orchestration for Claude Code: teams, roles, autopilot and task routing across skills and subagents
One runtime for Claude Code, Codex, OpenCode and more: a run counts as done only when checks the agent did not write pass
A memory and coordination layer for coding agents: specs and issues live in git while agents work in parallel
A local dashboard for many Claude Code sessions: each job gets its own context and todo, agents spawn child agents and message each other
A teaching terminal coding agent in Python, built as a "nanoGPT for agents": read it, take it apart and fork it
A Ralph loop for long tasks: an agent in a Docker sandbox works through a PRD task list, checks each task with tests and commits until the list is done
README in short
The description opens with a project news feed and a link to the paper, followed by installation, a quick start, a section on the plugin for Claude Code and Codex, a table of supported agents, a how-it-works diagram and a list of example tasks. The end collects development instructions, contributor rules and a BibTeX citation. There is separate documentation on the project site, architecture notes in `CLAUDE.md`, rules for agent-authored contributions in `AGENTS.md`, and pytest tests in the repository.