Symphony: a spec for turning tickets into autonomous code runs

Everything worth knowing about openai/symphony: an open specification and reference implementation for reading work from a board, isolating each issue in a workspace, and running coding agents without continuous interactive supervision.

---

What Symphony is

Symphony is a service specification for orchestrating coding agents. It continuously reads work from an issue tracker — Linear in the spec’s first version — creates an isolated workspace per issue, and runs a code agent session there.

OpenAI’s repository shouldn’t be confused with a generic multi-agent framework or a finished SaaS product. The centerpiece is SPEC.md, a language-independent Draft v1 specification; it also includes an experimental reference implementation in Elixir. OpenAI describes it as a low-profile “engineering preview” intended for trusted environments.

Its goal is to shift the level of control: instead of supervising individual Codex sessions, a team manages tickets, review states, and acceptance criteria. A successful run can stop at a state defined by the workflow — for example, Human Review — and not necessarily merge or complete the work.

The origin: from harness engineering to managing work

OpenAI announced Symphony on April 27, 2026. The launch post frames it as the step after harness engineering: once a repository has tests, documentation, tools, and guardrails suitable for an agent, the bottleneck shifts to coordinating many tasks without constantly switching between sessions.

The team explains they first used this style for an internal project built entirely with Codex-generated code. Symphony turns the project board — Linear in the example — into a control plane so an agent can pick up tickets, create changes, follow CI, address review comments, and leave evidence for human review.

The project is officially from OpenAI and is published under the Apache-2.0 license. The README shows around 24,700 stars, 2,400 forks, and 167 subscribers at the time of the query recovered; these are changing GitHub figures, not a measure of production adoption.

Philosophy and principles

• The ticket is the unit of work. Symphony decides eligibility, dispatch, retries, and recovery from tracker state, not from manually opened sessions.

• One workspace per issue. Agent commands are scoped to the associated working directory; the space is preserved across runs and cleaned up when the issue reaches a terminal state.

• Policy versioned alongside the code. WORKFLOW.md contains the runtime prompt and configuration, so each team can version ticket rules, validation, and delivery within its own repository.

• Orchestration, not micromanagement. The service schedules and observes; the agent, via its own tools, usually makes comments, PR links, and ticket transitions.

• Project guardrails before autonomy. OpenAI argues the pattern works best when the repository already has solid tests, documentation, and automated controls.

How it works

The spec splits the system into layers. Workflow Loader reads WORKFLOW.md; the configuration layer validates values and environment references; the tracker adapter normalizes issues; the orchestrator handles polling, concurrency, retries, and reconciliation; the workspace manager prepares the per-ticket directory; and the agent communicates with a code app server over stdio.

Linear / issue tracker → Orchestrator → per-ticket isolated workspace
                                       → code agent
                                       → CI, review, and evidence
                                       → delivery state defined in WORKFLOW.md

The service keeps a single orchestration state in memory, runs polling with limited concurrency, stops jobs that stop being eligible, and applies exponential backoff on transient failures. It must also offer, at minimum, structured logs to operate several concurrent runs.

Main components

• SPEC.md: a portable, language-neutral behavior contract. It uses RFC 2119 terminology (MUST, SHOULD, etc.) and makes explicit the decisions each implementation must define.
• WORKFLOW.md: the repository’s own policy: YAML front matter for configuration and a prompt body for instructions, validations, and delivery state.
• Tracker adapter: in v1, Linear provides the source of issues, states, and metadata; the spec requires normalization before the orchestrator acts.
• Workspace manager: generates deterministic per-issue paths, applies lifecycle hooks, and preserves spaces across runs.
• Agent runner: builds the prompt from the ticket and workflow, launches the agent client, and returns updates to the orchestrator.
• State surface: optional; it can be a terminal, a panel, or another human view. The spec doesn’t mandate a rich UI.

The ecosystem

Symphony is designed to work with Codex’s app server, though SPEC.md avoids turning its details into a fixed protocol and asks you to consult that server’s generated or current documentation.

The repository offers two paths: building your own implementation in your preferred language from the specification, or trying the experimental Elixir reference. This separation matters: the specification is the primary asset; the reference shouldn’t be treated as a finished, universal solution.

The community has already created interpretations. broomva/symphony presents itself as a Rust implementation that queries Linear, GitHub, or Markdown and dispatches agents into per-ticket workspaces; it’s an independent project inspired by OpenAI’s spec, not software maintained by OpenAI. Contrabass also appeared, another Go implementation shown on Hacker News.

Quick-start guide

Preparation

The README recommends adopting harness engineering practices first: useful automated tests, up-to-date documentation, tools for inspecting CI, and clear rules for how a change gets accepted.

Then there are two options:

1. Ask a coding agent to implement Symphony per SPEC.md in the chosen language.
2. Use the reference implementation and follow elixir/README.md to prepare the environment and run the binary with a project WORKFLOW.md.

Typical flow

1. Draft WORKFLOW.md with eligible states, rules, validations, tools, and the human handoff point.
2. Connect Linear and host credentials for the tracker and agent.
3. Start the service so it polls issues at the defined cadence and reserves separate workspaces.
4. Let the agent implement, run tests, create or update the PR, and process comments per the repository’s policy.
5. Review the evidence package and accept, fix, or cancel from the chosen workflow.

Common pitfalls and fixes

• Starting with ambiguous tickets. OpenAI acknowledges not every task fits: problems with strong judgment calls or fuzzy definition still need interactive engineering sessions.
• Assuming workspace isolation equals a full sandbox. The spec isolates directories per issue, but it doesn’t require strong sandbox controls beyond the agent and the host OS.
• Leaving policy outside the repository. The purpose of WORKFLOW.md is for rules, prompt, and configuration to evolve alongside the code. Two copies can create confusion about the source of truth; there’s a specific discussion about this point.
• Auto-merging without a delivery stage. Symphony lets success end at human review; each team must define which controls enable a merge.
• Treating tracker credentials as a minor detail. The agent can operate tickets via native tools; secrets should be provided via host references and scoped to the minimum necessary.

Security and trust model

The specification requires every implementation to document its trust and security posture, but it doesn’t prescribe a single approvals, sandbox, or operator policy. It explicitly acknowledges that some implementations target trusted environments while others require stricter controls.

By design, Symphony is a scheduler/runner and ticket reader. Tracker writes — transitions, comments, and PR links — are usually made by the agent’s native tools. When credentials are handed off via host secret references, the agent’s child process doesn’t need a second direct authentication with the tracker.

The safe practice is therefore separating environments, limiting credentials, requiring CI and human review before terminal states, and not turning on an autonomous flow over untrusted repositories or boards. These controls are consistent with the specification and the preview notice; they don’t substitute for an OpenAI security certification.

How the community received it

Visible reception combines technical interest and caution. On Reddit, the r/OpenAI announcement got 44 upvotes, and one comment characterized it as project management more than “orchestration”; that’s an individual opinion, but it captures well the operational-level shift the project pursues.

One author published a Rust implementation based on the spec and claimed to have processed 24 tickets through the implement-PR-automated review-human approval cycle. It’s an unaudited personal report, not an official Symphony metric.

GitHub discussions include derivative implementations, tools that generate WORKFLOW.md, and security findings for the Elixir reference. They establish that experimentation on the spec exists, not that those solutions have been evaluated or approved by OpenAI.

Symphony versus other approaches

Approach	Verifiable overlap	Verifiable difference
An interactive Codex session	Both use a coding agent to modify a repository.	Symphony pulls work from a tracker, schedules persistent runs, and keeps a versioned delivery policy.
Traditional CI automation	Both react to states and run repeatable processes.	Symphony assigns an agent an issue and a workspace, letting it reason and use tools within a repository policy.
broomva/symphony	Implements the ticket, isolated workspace, and agent session pattern.	It’s a community Rust implementation that extends the declared work origins; it’s not OpenAI’s reference.
Contrabass	Draws on the spec and uses agent orchestration for engineering tasks.	It’s a third-party Go/Charm Stack project presented as a Show HN.

Use cases and who this repository can help

• Teams with well-defined boards who want to turn low- or medium-risk issues into reviewable change proposals.
• Repositories with a good harness — tests, CI, conventions, and documentation — that can give the agent objective success signals.
• Teams suffering from context switching while coordinating several agent sessions and preferring to control queue, states, and deliverables.
• Internal platform developers who want to implement the pattern in another language or tracker, using the spec as a contract.

It isn’t a generic solution for any backlog: ambiguous, high-risk, or continuous expert-judgment tasks still need direct human direction.

Resources

• Repository: https://github.com/openai/symphony
• Specification: https://github.com/openai/symphony/blob/main/SPEC.md
• Elixir implementation: https://github.com/openai/symphony/tree/main/elixir
• OpenAI announcement: https://openai.com/index/open-source-codex-orchestration-symphony/
• Discussions: https://github.com/openai/symphony/discussions
• Community Rust implementation: https://github.com/broomva/symphony

---

Note: this article was compiled from the specification, repository, official announcement, and public conversations retrieved on August 17, 2026. Symphony declares itself Draft v1 and an experimental preview; its details can change.