CORAL: Git Worktrees, a Grader Daemon, and Coding Agents That Share Notes

The problem CORAL addresses: parallel agents that overwrite each other

Run two coding agents against the same checkout and the second one's edits land on top of the first. Run them against separate clones and they stop learning from each other. CORAL's answer is to give every agent its own git worktree while keeping one shared state directory, so file edits stay isolated and knowledge does not. The README describes the target user indirectly: someone with a codebase and a grader. The quickstart example is a single function, sample() in saga/decode.py, with the instruction to make it faster without changing its output. That is the shape of task CORAL expects. The project also names a research framing, with a paper titled "CORAL: Towards Autonomous Multi-Agent Evolution for Open-Ended Discovery" and acceptance at COLM 2026. The infrastructure and the paper are the same repository, which matters for anyone deciding whether to treat this as a product or as a research artifact with a CLI.

Worktrees, .coral/public/, and the grader daemon

The mechanism is described in one paragraph of the README and one architecture diagram. Each agent runs in its own git worktree. Shared state, listed as attempts, notes and skills, lives in .coral/public/ and is symlinked into every worktree, so an agent writing a note is writing into a path every other agent can read immediately. A grader daemon scores every commit. Separately, a manager process interrupts agents with heartbeat prompts named reflect, consolidate and pivot. Those three prompts are the interesting part of the design. A grader tells an agent whether a commit was better; a heartbeat prompt tells it to stop and reconsider. The README does not state how the manager chooses which prompt to send or on what schedule, and that gap matters if you plan to tune the loop. Version 0.6.0 added multi-island runs, which partition agents into isolated islands with scoped attempts, notes, skills and heartbeat state, plus migration between islands. Islands are the mechanism for exploration breadth: instead of one shared pool of notes, you get several, and agents can move between them.

Installing CORAL and scaffolding a task

The README gives a one-line installer that pulls the latest release through uv tool install, with CORAL_VERSION=<tag> to pin a specific release. After that, two commands: coral init my-task scaffolds a task, and coral start -c task.yaml launches agents. Python 3.11 or newer is required per the badge. Graders are wired through the grader.entrypoint config key pointing at a packaged grader. This is a change worth noting: as of the 2026-06-13 note, legacy eval/grader.py auto-discovery is deprecated and removed, so any task copied from older material that relied on that path will not work. Agent runtimes are selected with agents.runtime, with values claude_code (the default), codex, dsh, cursor, kiro, opencode and pi. Each agent must be installed and authenticated separately, which means CORAL is not a self-contained runtime; it orchestrates CLIs you supply. A LiteLLM gateway is documented for custom models. There is also a plugin path for people who would rather not memorize the CLI: a skills-first bundle, explicitly no MCP, installed through the Claude Code or Codex plugin marketplace, with skills named coral-quickstart, setting-up-coral, creating-a-coral-task and running-coral-experiments.

Isolation is real in Docker and opt-in on the host

This is the sharpest limitation in the material. The 2026-06-24 note states that the Docker session isolates the agent from the grader: each agent runs as an unprivileged user while manager and grader stay root, so agents cannot read .coral/private/ (grader venv, answer keys), not even via Bash. The same note then says that on the host this stays opt-in via agents.isolate_user. Read those two sentences together. If you run CORAL directly on your machine and do not set agents.isolate_user, an agent process runs with your privileges and .coral/private/ is not protected by user separation. The documentation does not claim otherwise, but the security property people will assume from "isolated workspaces" is stronger than what the host default provides. A second constraint is that every agent CLI must be installed and authenticated independently, so the failure surface includes each vendor's own login and quota behaviour, not just CORAL.

When a grader is the wrong shape for your problem

CORAL's loop depends on scoring every commit. If your objective is a number a script can compute, the loop has a signal. If it is not, you need a judge. CORAL ships rubric judges, described as two reusable LLM-judge grader packages for open-ended tasks such as reports, memos and legal analysis, added 2026-04-24. That is a genuine attempt to widen the range of scorable work, but it changes the nature of the signal: a rubric judge is itself a model call, so the score can drift between runs, and the README does not describe how judge variance is handled. For tasks where a grader is genuinely hard to write, a plain agent session with a human reviewing diffs is simpler and has fewer moving parts. CORAL's value comes from running many attempts in parallel against a repeatable score, and that value shrinks as the score becomes noisier.

How CORAL differs from a generic agent orchestrator

A general-purpose orchestrator such as LangGraph or a plain multi-agent framework gives you message passing and control flow, and leaves evaluation to you. CORAL treats the grader as a first-class component: a daemon scores every commit, and the score is what the shared state is organized around. The other difference is the unit of isolation. Message-passing frameworks isolate conversations; CORAL isolates git worktrees and symlinks a shared directory into each one. That choice assumes the work is code in a repository and the improvement is a diff, which is narrower than a general orchestrator and more concrete. If your agents are producing prose or analysis rather than commits, the worktree model buys you nothing, and the rubric judge path is the only part of CORAL that applies.

Maintenance cost and the Apache-2.0 licence

Release cadence is visible and fast: v0.7.19 on 2026-08-20, v0.7.20 on 2026-08-30, v0.7.21 on 2026-09-06, with the last push to main on 2026-09-08. Three releases in roughly three weeks means pinning matters. The installer supports CORAL_VERSION=<tag>, and that is the practical way to avoid a task breaking under you. The removal of eval/grader.py auto-discovery is the concrete example of what an upgrade can cost: a config that worked before the 2026-06-13 change now needs grader.entrypoint pointing at a packaged grader. On licensing, the repository is Apache-2.0, which permits commercial use and modification and includes an explicit patent grant; it also requires that you preserve notices and state changes. That is a summary of the licence text, not legal advice, and your own counsel should review anything you ship. The deeper maintenance cost is the agent CLIs themselves. CORAL orchestrates Claude Code, Codex, OpenCode and others, so a breaking change in any of those tools lands on you even when CORAL's own version is pinned.

Editorial conclusion

CORAL suits teams that already have a codebase and a metric they can express as a grader, and who want several coding agents working the same problem without overwriting each other. It is the wrong tool if your objective cannot be scored automatically, or if you cannot install and authenticate a coding agent CLI. Before adopting, verify three things on your own machine: that a grader you write passes coral validate, that the runtime you want appears in agents.runtime and is authenticated, and whether agents.isolate_user is enabled on your host, since without it the isolation described for the Docker session does not apply.

Official sources

1. Human-Agent-Society/CORAL on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases