Symphony - OpenAI's Spec for Running Codex Against Your Linear Backlog

You’ve been managing your Linear board manually — assigning yourself tickets, opening Claude Code or Cursor, copying the description in, walking the agent through implementation, opening the PR, merging it.

Symphony from OpenAI is the question “what if the loop above ran without you?” — a service that polls Linear, spawns a Codex session per ticket inside an isolated workspace, and keeps it working until the PR lands.

You’re left managing what to build, not how the agent builds it.

What is Symphony?

Symphony is a self-hostable orchestrator service from OpenAI that turns project work into isolated, autonomous implementation runs.

It is the successor concept to OpenAI’s Harness Engineering methodology — moving from manually driving coding agents to running them as a daemon against your ticket backlog.

The repo ships two things:

1. SPEC.md — a 2,169-line language-agnostic RFC-2119 specification of the service contract
2. elixir/ — an Elixir/OTP reference implementation, marked as engineering preview

“Symphony is a low-key engineering preview for testing in trusted environments.”

Symphony on GitHub OpenAI Harness Engineering Codex App Server docs

What makes it different

• 📜 Spec-first, reference-second — Symphony is primarily a specification; the Elixir code is one reference, not the canonical implementation. The README literally suggests: “Tell your favorite coding agent to build Symphony in a programming language of your choice”
• 🎟️ Linear-native — polls Linear on a fixed cadence; spawns sessions for tickets in active states; stops when tickets move to terminal states
• 🤖 Codex App Server — agents run via Codex’s App Server mode, with workspace-write sandboxing and configurable approval policy
• 📁 Per-issue workspaces — every ticket gets its own directory at ~/code/symphony-workspaces/<id>/; workspaces persist across runs and are cleaned up on terminal state transitions
• 📝 WORKFLOW.md is the contract — repo-owned YAML front matter + Markdown prompt template; the agent’s policy lives in your codebase, versioned with your code
• 🔄 Restart recovery without a database — orchestrator state is reconstructed from tracker + filesystem on startup, no persistent DB required
• 🛡️ Trust posture is implementation-defined — the spec deliberately doesn’t mandate one approval model; Elixir reference defaults to approval_policy: never for trusted internal use
• ⚖️ Apache 2.0 — commercially permissive, OpenAI’s stamp on the spec

Where Symphony Sits in the AI Stack

Symphony belongs to the orchestration layer, alongside Paperclip — but with a different design point. The full five-layer stack we’ve covered on this site:

The honest contrast vs Paperclip — the closest neighbor:

Symphony is simpler, more opinionated, and vendor-flavored (Codex + Linear). Paperclip is broader, more configurable, and vendor-neutral (any agent + any tracker on the roadmap). They occupy the same architectural slot but answer different questions:

• Pick Symphony if you already use Linear + OpenAI Codex, want a small auditable spec, and trust your codebase enough to run Codex with approval_policy: never
• Pick Paperclip if you mix agent providers, want multi-company support, and need budget hard-stops as a core feature

The five design principles (the actual pitch)

The README is short, but the SPEC is long. The opinionated claims behind Symphony are visible if you read both together:

1. The spec is the product; the implementation is one option. This is unusual. OpenAI shipped a 2,169-line RFC-2119 spec and explicitly tells users: “Tell your coding agent to build Symphony in a programming language of your choice.” The Elixir code is a reference, not the canonical answer. Symphony’s bet is that AI coding agents are now capable enough that a tight specification is a more valuable artifact than any single implementation.

2. Policy lives in the target repo, not in Symphony. WORKFLOW.md — the file that defines what the agent does for each ticket state, how it handles blockers, when it hands off to humans — lives in the codebase being worked on, not in Symphony’s config. The agent’s behavior evolves with the codebase. Symphony is intentionally policy-free.

3. Symphony is a runner, not an editor. The SPEC is explicit: Symphony schedules and isolates agent runs. The agent itself does the ticket-writing, PR-opening, status-transitioning work using tools provided in the workflow environment. This means Symphony is much smaller than it could be — and Symphony updates don’t change your team’s ticket workflow.

4. Trust posture is implementation-defined, not mandated. The spec deliberately refuses to prescribe a single approval / sandbox / confirmation policy. The Elixir reference targets trusted internal environments with approval_policy: never + thread_sandbox: workspace-write; other implementations can require manual approvals, run in stronger sandboxes, or layer on additional governance. This is the spec authors saying “we know orchestration needs vary.”

5. Restart recovery without a database. The orchestrator state is rebuildable from the tracker (Linear) and the filesystem (workspaces) on startup. No persistent DB requirement. This is a deliberate non-goal — the spec says explicitly that exact in-memory scheduler state is not restored, only enough to resume work without losing tickets. The simplicity is the feature.

The whole thing is the opposite of a maximalist platform pitch. Symphony is small, opinionated, and unapologetic about what it doesn’t do.

Self-Hosting Symphony

The Elixir reference is what you’d run if you don’t want to build your own. The README is upfront about its status:

“Symphony Elixir is prototype software intended for evaluation only and is presented as-is. We recommend implementing your own hardened version based on SPEC.md.”

If you want the experience anyway, here’s how.

Requirements

• Elixir 1.19 + Erlang/OTP (use mise )
• Codex CLI with App Server support
• A Linear workspace + Personal API key (Settings → Security & access → Personal API keys)
• A codebase set up for harness engineering

Install

git clone https://github.com/openai/symphony
cd symphony/elixir
mise trust
mise install
mise exec -- mix setup
mise exec -- mix build

Configure

1. Copy elixir/WORKFLOW.md into your target codebase’s repo
2. Edit the YAML front matter — set tracker.project_slug to your Linear project’s slug, point hooks.after_create at your repo’s clone command
3. Edit the Markdown body — describe the agent’s policy for ticket handling
4. Optionally copy the commit, push, pull, land, and linear skill files into your repo

Run

export LINEAR_API_KEY=lin_api_...

mise exec -- ./bin/symphony ./WORKFLOW.md

# Or with the optional Phoenix dashboard:
mise exec -- ./bin/symphony ./WORKFLOW.md --port 4000

The orchestrator polls Linear every interval_ms (default 5000), picks up tickets in your configured active_states, spawns Codex in each ticket’s workspace, and works until the ticket transitions to a terminal state.

codex:
  command: codex --config shell_environment_policy.inherit=all --config 'model="gpt-5.5"' --config model_reasoning_effort=xhigh app-server
  approval_policy: never
  thread_sandbox: workspace-write
  turn_sandbox_policy:
    type: workspaceWrite

Implement Symphony according to the following spec:
https://github.com/openai/symphony/blob/main/SPEC.md

What Symphony Is Not

A successful Symphony run can end at a workflow-defined handoff state (e.g. Human Review) — not necessarily Done. The agent decides when it’s blocked or when humans need to take over; Symphony just keeps the loop running.

Conclusion

Symphony is a tightly-scoped, opinionated answer to “what if I never had to start a Codex session manually for a Linear ticket again?” The fact that the primary deliverable is a 2,169-line spec (with an Elixir reference as one option) is itself the most interesting design choice — OpenAI is betting that AI coding agents are now good enough that a precise specification is more valuable than any specific implementation.

For teams already using Linear + Codex who want autonomous coding-agent runs on their backlog, it’s the right shape of project. For teams that need broader agent/tracker support or stronger governance features, Paperclip is the better orchestration choice — Symphony stays focused.

Related tools worth knowing:

• Paperclip — broader orchestration layer; multi-agent, multi-company, budget hard-stops
• OpenAI Codex — the agent Symphony runs; App Server mode is what Symphony uses to drive it
• Linear — the (currently only) supported ticket tracker
• Agent OS — standards layer that runs inside the Codex sessions Symphony spawns
• OpenSpec — workflow layer that runs inside the Codex sessions Symphony spawns