OpenAI Symphony: The Complete Guide to Autonomous Coding Agent Orchestration
What if your entire team's Linear board could manage itself — issues picked up, code written, tests run, PRs reviewed, and work landed — without engineers supervising a single coding agent? Symphony by OpenAI does exactly that. With 9,000+ GitHub stars in its first two weeks, Symphony turns project work into isolated, autonomous implementation runs on Erlang/BEAM, letting teams manage work, not agents.
What Is Symphony?
Symphony is an open-source automation framework by OpenAI that continuously reads work from an issue tracker (Linear), creates an isolated workspace for each issue, and runs a coding agent session (Codex) inside that workspace. Engineers manage a Kanban board; Symphony handles everything else.
- Language: Elixir (Erlang/BEAM)
- License: Apache 2.0
- Stars: 9,000+ ⭐
- Forks: 627
- Created: February 2026
- Team: OpenAI
The Core Concept: Manage Work, Not Agents
Symphony solves four operational problems:
- Repeatable daemon workflow — Issue execution isn't manual scripts; it's a continuous service
- Per-issue workspace isolation — Agent commands run only inside dedicated workspace directories
- In-repo workflow policy —
WORKFLOW.mdversions the agent prompt and runtime settings with the code - Multi-run observability — Debug and monitor multiple concurrent agent runs
The key insight: engineers shift from supervising coding agents to managing a task board. Symphony monitors Linear, spawns Codex agents, and produces proof of work (CI status, PR review feedback, complexity analysis, walkthrough videos).
Architecture: 7 Components on BEAM
Built on Erlang/BEAM for fault tolerance and concurrency:
1. Workflow Loader
Reads WORKFLOW.md from the repository, parses YAML front matter and prompt body.
2. Config Layer
Typed getters for workflow config, defaults, environment variable indirection, validation.
3. Issue Tracker Client
Fetches candidate issues from Linear, normalizes payloads into stable issue models, handles reconciliation.
4. Orchestrator
Owns the poll tick and in-memory state. Decides which issues to dispatch, retry, stop, or release. Tracks session metrics.
5. Workspace Manager
Maps issue identifiers to workspace paths, creates per-issue directories, runs lifecycle hooks, cleans terminal workspaces.
6. Agent Runner
Creates workspace, builds prompt from issue + workflow template, launches the coding agent, streams updates.
7. Status Surface (Optional)
Terminal output, dashboard, or operator-facing view for runtime status.
The 6-Layer Architecture
1. Policy Layer → WORKFLOW.md (repo-defined prompts + rules)
2. Configuration Layer → Typed runtime settings from front matter
3. Coordination Layer → Polling loop, eligibility, concurrency, retries
4. Execution Layer → Workspace + agent subprocess
5. Integration Layer → Linear adapter (API calls + normalization)
6. Observability Layer → Logs + optional status surface
Workflow: From Issue to Landed PR
1. Engineer creates issue on Linear board → "Ready for Dev"
2. Symphony poll tick picks up the issue
3. Workspace Manager creates isolated per-issue directory
4. Agent Runner builds prompt from WORKFLOW.md + issue context
5. Codex agent executes: writes code, runs tests, creates PR
6. Proof of work produced: CI status, PR review, complexity analysis, walkthrough video
7. Engineer reviews proof of work
8. If accepted → Symphony lands the PR safely
9. If rejected → Retry with feedback
Getting Started
Option 1: Build Your Own
Symphony publishes a comprehensive SPEC.md — a 29-section specification. Tell your favorite coding agent:
"Implement Symphony according to https://github.com/openai/symphony/blob/main/SPEC.md"
Option 2: Use the Elixir Reference Implementation
# Follow the setup instructions
# See elixir/README.md for environment setup
Requirements
- Harness engineering — Symphony works best in codebases that have adopted harness engineering
- Linear account for issue tracking
- Codex (or compatible coding agent)
The SPEC.md: A Language-Agnostic Blueprint
Symphony's 29-section specification covers:
| Section | What It Defines |
|---|---|
| Problem Statement | Four operational problems solved |
| System Overview | 7 components, 6 abstraction layers |
| Core Domain Model | Entities, stable identifiers, normalization |
| Workflow Specification | WORKFLOW.md format, YAML front matter schema |
| Configuration | Source precedence, dynamic reload, dispatch validation |
| Orchestration State Machine | Issue states, run attempt lifecycle, transitions |
| Polling & Scheduling | Poll loop, candidate selection, concurrency control |
| Workspace Management | Layout, creation, hooks, safety invariants |
| Agent Runner Protocol | Launch contract, session handshake, streaming turns |
| Issue Tracker Integration | Linear-compatible operations, query semantics |
| Prompt Construction | Inputs, rendering rules, retry semantics |
| Logging & Observability | Structured logs, runtime snapshots, metrics |
| Failure Model | Failure classes, recovery, operator intervention |
| Security & Safety | Trust boundaries, filesystem safety, secret handling |
| Reference Algorithms | Language-agnostic pseudocode for all operations |
| Test Matrix | 8 test categories for conformance validation |
| Implementation Checklist | Definition of done for conformant implementations |
Symphony vs Alternatives
Category: This tool is an autonomous coding agent orchestration framework.
| Feature | Symphony | SWE-agent | Codex CLI |
|---|---|---|---|
| Focus | Project-level orchestration | Issue-level autonomous fixing | Interactive coding agent |
| Stars | 9K ⭐ | 18.7K ⭐ | 63.7K ⭐ |
| License | Apache 2.0 | MIT | Apache 2.0 |
| Language | Elixir (BEAM) | Python | Rust |
| Issue Tracker Integration | ✅ Linear (native) | ✅ GitHub Issues | ❌ |
| Isolated Workspaces | ✅ Per-issue directories | ✅ Docker sandbox | ❌ |
| Concurrent Runs | ✅ BEAM concurrency | ❌ Sequential | ❌ |
| Proof of Work | ✅ CI + PR review + walkthrough | ✅ Patch output | ❌ |
WORKFLOW.md (repo policy) | ✅ | ❌ | ❌ |
| State Machine | ✅ Issue orchestration states | ❌ | ❌ |
| Retry / Backoff | ✅ Configurable | ❌ | ❌ |
| Fault Tolerance | ✅ Erlang/OTP supervision | ❌ | ❌ |
| Multi-issue Orchestration | ✅ Board-level automation | ❌ Single issue | ❌ |
| LLM Support | Codex (OpenAI) | ✅ Any LLM (GPT, Claude, etc.) | Codex (OpenAI) |
| Sandbox Security | ✅ Workspace isolation | ✅ Docker container | ✅ Sandbox-first |
| SWE-bench Performance | N/A | ✅ NeurIPS 2024 paper | N/A |
| Cybersecurity Use | ❌ | ✅ Offensive security | ❌ |
| Approval Modes | ✅ Configurable | ❌ | ✅ 3 modes (suggest/auto/full) |
| Spec / Portability | ✅ 29-section SPEC.md | ❌ | ❌ |
| Team | OpenAI | Princeton NLP | OpenAI |
When to choose Symphony: You need project-level orchestration that monitors a Linear board, spawns concurrent isolated agent runs, produces proof of work, and lands PRs automatically. Best for teams with harness engineering practices who want to manage work, not agents. Erlang/BEAM gives fault tolerance and concurrency. The SPEC.md makes it portable to any language.
When to choose SWE-agent: You need to automatically fix individual GitHub issues with any LLM. Academic-grade with a NeurIPS 2024 paper. Specialized Agent-Computer Interface, Docker sandbox, and SWE-bench benchmarks. Also usable for offensive cybersecurity and competitive coding.
When to choose Codex CLI: You want an interactive coding agent in the terminal with 3 approval modes (suggest, auto-edit, full-auto). Sandbox-first, Rust-based, by OpenAI. Not an orchestration framework — a single-agent tool.
Key Concepts
Harness Engineering
Symphony requires codebases that have adopted harness engineering — the practice of making codebases agent-friendly with clear CI pipelines, test harnesses, and deterministic builds.
WORKFLOW.md
The repo-versioned workflow policy:
---
tracker:
kind: linear
agent:
model: codex
workspace:
hooks:
pre_run: "./scripts/setup.sh"
---
You are an AI software engineer. Your task is to implement the following issue...
Proof of Work
Every agent run produces verifiable artifacts:
- CI pipeline status (pass/fail)
- PR review feedback
- Complexity analysis
- Walkthrough video of changes
Conclusion
Symphony represents OpenAI's vision of the future of software engineering: teams manage a Kanban board while AI agents handle the implementation. Built on Erlang/BEAM for fault tolerance, driven by a 29-section open specification that anyone can implement in any language, and designed around proof of work and workspace isolation — Symphony is the orchestration layer between your project management and your coding agents.