---
title: Architecture
description: 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 |
