Noureddine RAMDI / CORAL: orchestrating autonomous AI coding agents with git worktree isolation and shared state

Created Mon, 04 May 2026 10:23:01 +0000 Modified Sat, 23 May 2026 20:41:27 +0000
945 Words
github-stars python ai-agents git-worktree multi-agent-system cli evaluation-loop

Human-Agent-Society/CORAL

CORAL tackles the challenge of coordinating multiple autonomous AI coding agents working simultaneously on code improvement tasks. The unique technical angle here is how it leverages Git’s worktree functionality combined with symlinked shared directories to enable isolated yet collaborative agent workflows without expensive synchronization overhead.

orchestrating autonomous AI coding agents with git worktree isolation

At its core, CORAL is a Python infrastructure that runs multiple AI coding agents (such as Claude Code, Codex, and OpenCode) as subprocesses. Each agent operates within its own isolated Git worktree branch. This isolation allows agents to work independently without stepping on each other’s changes directly.

What makes CORAL architecturally interesting is how these isolated branches share state. Instead of duplicating data or using complex synchronization mechanisms, CORAL uses symbolic links to a shared .coral/ directory. This directory contains the agents’ attempts, notes, and skills, all accessible in real-time to each agent despite branch isolation.

This setup enables emergent collaboration patterns. Agents can see the latest progress others have made instantly through the .coral/public/ symlink, even though each agent commits in its own branch. The shared state acts as a knowledge base and communication channel among agents, fostering iterative improvements.

The repository provides a command-line interface with over 17 commands to control the runs—starting, stopping, resuming, and monitoring agent activity. A web dashboard complements this with visualization and monitoring capabilities.

The system also includes a “warm-start” research phase, where agents perform structured literature review before the coding begins. This phase helps bootstrap the agents with relevant context, improving downstream code generation and evaluation.

leveraging evaluation-driven iterative improvement loops

CORAL distinguishes itself by embedding an evaluation-driven optimization loop directly into the multi-agent workflow. Agents generate code attempts, then evaluate their own work via a grader interface that stages, commits, and scores these attempts in one shot.

The grader interface is pivotal: it automates the process of assessing code quality and performance, feeding back results to the agents so they can iteratively refine their outputs. This closed feedback loop is essential for autonomous AI code evolution.

From a code quality perspective, the Python codebase is well organized around this loop and the multi-agent orchestration. The use of Git worktrees is a clever design tradeoff—while it introduces some complexity in branch management and repository state, it avoids the heavier synchronization or communication overhead that comes with other multi-agent coordination approaches.

The CLI tooling and web dashboard indicate attention to developer experience and operational transparency, which are often neglected in research-oriented AI projects.

One limitation to keep in mind is that CORAL depends on users having the underlying AI coding agents properly installed and authenticated beforehand. The system itself does not handle agent installation or credential management, which can be a barrier for some.

quick start with coral

The project README provides these installation and usage instructions verbatim:

git clone https://github.com/Human-Agent-Society/CORAL.git
cd CORAL

# install uv from https://github.com/astral-sh/uv
uv sync                   # (optionally add --extra ui to include dashboard dependencies)

CORAL supports multiple coding agents that run as subprocesses interacting via the terminal. Supported agents include:

  • Claude Code (Anthropic’s agentic coding tool, default and most tested)
  • Codex (OpenAI’s open-source coding agent)
  • OpenCode (open-source terminal-based AI coding agent)

Before running CORAL, you must install and authenticate your chosen agent(s) separately. The README highlights the importance of setting permissions and environment variables correctly to avoid runtime failures.

Agent configuration is YAML-based, specifying the runtime, agent count, and model name, for example:

agents:
  runtime: claude_code
  count: 3
  model: opus

This sets up a run with three Claude Code agents using the “opus” model.

who should consider coral?

CORAL is a solid choice if you’re exploring multi-agent AI-driven code optimization or research workflows where autonomous agents iteratively improve codebases. Its architecture for state sharing via Git worktrees and symlinks is worth understanding if you face challenges coordinating concurrent autonomous agents without heavy synchronization.

The tradeoff is the added complexity of managing Git branches and the prerequisite that your agents must be fully installed and authenticated externally. This infrastructure is not a plug-and-play AI coding assistant but rather a platform for experimentation with multi-agent collaboration patterns.

If you’re comfortable with Python, Git internals, and have a use case involving open-ended code optimization by multiple AI agents, CORAL offers a neat, well-instrumented environment to explore these concepts.

That said, the system’s reliance on subprocess-based AI agents interacting via terminals means it’s limited to agents that support this mode. Also, the current design assumes a certain level of Git fluency and operational discipline.

In summary, CORAL delivers an elegant solution for orchestrating multi-agent AI coding experiments with a lightweight yet powerful architecture that balances isolation and collaboration through Git worktrees and shared state symlinks. Its evaluation-driven loop and warm-start research phase further enhance its utility in iterative code improvement scenarios.

→ GitHub Repo: Human-Agent-Society/CORAL ⭐ 611 · Python