Codex LOOP Orchestra

The control loop that keeps an engineering team of 100+ Codex agents running.

Highlights · Control loop · Quickstart · Why LOOP · Architecture · 中文 · Docs

Codex can launch subagents in parallel. LOOP adds the scheduling, isolation, independent audit, and observability needed to turn a one-shot batch into a self-replenishing engineering system.

Give LOOP a goal and a concurrency target. It breaks the work into tasks, dispatches them, and fills each newly available slot until the backlog is empty. Small workloads can remain visible in Codex Desktop; larger waves can run through supervised WSL headless workers. The root, execution, and audit stages can use models from different providers, while one dashboard shows what every agent is doing. You no longer have to keep asking the system to continue, and you retain final control over every merge.

Highlights

• Tested at 100+ concurrent agents: LOOP delivers stable, hundred-agent concurrency on the widely used Codex harness by combining Desktop agents with supervised WSL/CLI workers.
• Set the target once; LOOP keeps it filled: LOOP measures the agents actually running and refills open slots until the bounded backlog is empty—no repeated “continue” prompts required.
• Independent model choice at all three stages: The root agent orchestrates, execution agents implement, and audit agents review. Each stage can use a different model provider, including third-party models exposed through a Codex-compatible gateway such as OpenCodex.
• Root-agent orchestration with a DAG gate: The root plans and adjudicates. Dependency and write-scope checks run before tasks enter isolated Git worktrees.
• About 75% lower root-agent token use: The root model no longer performs search, bulk execution, waiting, or routine retries. It spends its tokens on planning and adjudication instead.
• WSL with an IPython/IPybox-style persistent compute container: An on-demand Python kernel preserves DataFrames, indexes, and counters across calls and processes large files, datasets, and intermediate results outside the model context.
• Desktop launches and supervises CLI concurrency: Keep the root conversation and a small visible agent set in Desktop while supervised codex exec processes expand larger execution waves into the WSL headless runtime.
• Agent Monitoring Web UI: See every Desktop and CLI agent in one browser view, including its task name, observed model, runtime, health, refill deficit, and remaining capacity.
• Durable replay and lifecycle supervision: Typed append-only events, generation-aware rosters, process-tree supervision, and deterministic reconciliation let an interrupted control loop resume from files instead of reconstructing state from chat memory.
• Stable present/past evidence views: run_view.py summarizes the live run; run_evidence.py builds a compact index over completed packets, decisions, reports, and terminal lifecycle evidence.

The control loop is the product

Many agent harnesses can start a batch of agents. LOOP solves the harder problem: keeping the requested concurrency level filled for as long as useful parallel work remains, while isolating writes, making acceptance reproducible, and reserving release authority for a human.

In plain language: Set the goal and concurrency once. LOOP handles decomposition, dispatch, refill, and verification. When one agent finishes, another takes the open slot. Scripts handle routine waiting and retries; only exceptions that require judgment are escalated to the root agent.

What that means for you: No more repeatedly typing “continue” or “start more agents.” Parallel execution reduces elapsed time, isolated worktrees prevent agents from overwriting one another, and an independent model audit helps catch shared blind spots.

The control loop enforces these rules:

1. The root agent produces a bounded plan and does not perform bulk execution itself.
2. Every task packet declares its goal, authorized paths, acceptance commands, and constraints.
3. A DAG gate rejects cyclic dependencies and overlapping write scopes before dispatch.
4. Desktop agents and headless workers run in isolated Git worktrees with an explicit role, model, and reasoning effort.
5. Scripts rerun acceptance commands, verify diff boundaries, and record typed lifecycle events.
6. The independent L2 audit stage may approve, request rework, rank alternatives, or escalate; it cannot publish.
7. Only exceptions that cannot be handled by policy return to the root agent. A human must trigger the final merge and release.
8. Scripts and state machines handle waiting, status checks, counts, routine retries, and state transitions without consuming additional root-model turns.

Models make judgments. Code manages state. Independent models audit the work. Humans release it.

Quickstart

Give this repository to Codex or another coding agent and paste:

Install Codex LOOP Orchestra from https://github.com/LEO001020/codex-loop-orchestra.
Read AGENT_INSTALL.md first. Inspect my environment, show the dry-run and backups,
wait for my approval, then activate LOOP and verify the installation.
Never read, print, or change my API credentials.

Prefer to install manually? Jump to Installation details, or read the complete Windows/Linux/WSL guide.

Why LOOP exists

LOOP is not simply a way to start more agents. Each part of the system addresses a failure mode that appears when a native agent harness is used for sustained, high-concurrency, multi-model engineering:

LOOP has been tested with more than 100 concurrent agents. The public package ships with a more conservative default of 20 active agents per parent task and 80 across the Desktop and headless runtimes on one machine; users can raise those values to match the workload, model-provider capacity, and local hardware.

The 10–20 range is a maintainer observation from one environment that motivated the dual-plane design, not a published benchmark or an official Codex limit.

How LOOP works

LOOP separates planning, execution, audit, state management, and release authority.