Symphony: Open‑Source Spec for Codex Orchestration

Overview

Symphony is an open‑source specification that defines how to orchestrate coding agents using an issue tracker as the control plane. It enables every open task to be assigned a dedicated agent workspace that runs continuously until the task is complete, reducing the need for human supervision of individual Codex sessions.

Technical Specification

The Symphony spec is a single SPEC.md file that describes a language‑agnostic service. It outlines core components such as a workflow loader, issue tracker client, orchestrator, workspace manager, agent runner, and optional status surface. Implementations must respect safety invariants: agents run only inside per‑issue workspace paths, workspace keys are sanitized to `[A-Za-z0-9._-9 workspace paths stay within a configured root.

Workflow Definition (WORKFLOW.md)

Each repository adopts Symphony by adding a WORKFLOW.md file that contains YAML front matter and a prompt template. The front matter declares the tracker kind (currently linear), polling interval, workspace root, hooks, and agent/Codex settings. The prompt template receives the normalized issue object and an optional attempt variable, allowing different instructions for first runs, continuations, and retries.

Orchestration Mechanics

Symphony polls the tracker on a fixed cadence, dispatches work up to global and per‑state concurrency limits, and maintains an in‑memory runtime state. It reconciles running agents each tick, detects stalls via a configurable timeout, and retries failed attempts with exponential backoff. Successful runs may end at a workflow‑defined handoff state (e.g., Human Review) rather than requiring the tracker to reach a terminal state.

Implementation & Adoption

The reference implementation is written in Elixir, chosen for its concurrency primitives, but the spec is deliberately minimal so agents can implement Symphony in any language. OpenAI used Symphony internally and observed a 500% increase in landed pull requests on some teams within the first three weeks. After open‑sourcing, the repository received over 15K GitHub stars as of April 23, and Linear’s founder noted a spike in workspaces created following the release.

Implications & Future Work

By treating agents as objective‑driven workers rather than micromanaged sessions, Symphony shifts the bottleneck from writing code to managing agentic work. Teams can now file speculative tasks cheaply, let agents explore ideas, and focus human effort on harder, exploratory problems. OpenAI positions Symphony as a reference implementation and encourages developers to point their coding agents at the spec and repository to build tailored versions for their own environments.