Concepts
Architecture
How CORAL orchestrates autonomous coding agents.
CORAL follows a simple loop: spawn agents → agents read instructions → commit changes → eval → repeat.
System overview
┌─────────────────────────────────────────┐
│ coral start │
│ │
│ 1. Create .coral/ shared state │
│ 2. Create per-agent git worktrees │
│ 3. Spawn grader daemon │
│ 4. Generate CORAL.md instructions │
│ 5. Spawn agent subprocesses │
└────────────────────┬────────────────────┘
│
┌──────────────┼──────────────┐
│ │ │
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌─────────────────┐
│ Agent 1 │ │ Agent 2 │ │ Grader Daemon │
│ │ │ │ │ │
│ Edit code│ │ Edit code│ │ Poll pending │
│ commit │ │ commit │ │ git worktree │
│ write │ │ write │ │ run grader │
│ pending │ │ pending │ │ write score │
│ poll... │ │ poll... │ │ cleanup │
└──────────┘ └──────────┘ └─────────────────┘
│ │ ▲
└──────────────┴──────────────┘
.coral/public/attempts/
(pending → scored JSONs)Agents and the grader daemon communicate entirely through the filesystem — there is no RPC, no sockets, no message queue. Agents write pending attempt JSON files; the daemon reads them, grades, and writes back the results. Agents poll the same files until the score appears.
Directory layout
When you run coral start, the following structure is created:
results/<task-name>/<timestamp>/
├── .coral/ # Shared state directory
│ ├── config.yaml # Task configuration (copy)
│ ├── public/ # Visible to all agents
│ │ ├── attempts/ # JSON records of each eval
│ │ ├── notes/ # Agent-written insights
│ │ ├── skills/ # Reusable tools/scripts
│ │ ├── logs/ # Agent session logs
│ │ ├── heartbeat/ # Heartbeat action configs
│ │ ├── eval_count # Global eval counter
│ │ ├── grader_daemon.pid # Daemon process ID
│ │ └── grader_daemon_heartbeat # Daemon liveness timestamp
│ └── private/ # Hidden from agents
│ ├── eval/ # Grader code and test data
│ └── grader_checkouts/ # Ephemeral worktrees for grading
│
└── agents/
├── agent-1/ # Git worktree for agent 1
│ ├── .coral_dir # Points to shared .coral/
│ ├── .coral_agent_id # This agent's ID
│ ├── CORAL.md # Generated instructions
│ └── <task files> # Seeded from workspace.repo_path
│
└── agent-2/ # Git worktree for agent 2
└── ...Tech stack
| Component | Technology |
|---|---|
| Language | Python 3.11+ |
| Build system | Hatchling |
| Package manager | uv |
| Agent runtimes | Claude Code, Codex, OpenCode |
| Web dashboard | Starlette (backend) + React/Vite (frontend) |
| Key dependency | PyYAML |