Symphony Deep Dive: How OpenAI Turns Codex from a Chat Assistant into an Engineering Teammate
> Author: Symphony > Source: OpenAI > Repo: github.com/openai/symphony > Release: February 2026 > Format: SPEC.md (pure Markdown)
---
1. What Is It, In One Sentence
Symphony is OpenAI's open-source agent orchestration framework. Written as a plain spec document (rather than Linear), it organizes coding agent behavior — running multiple agents on a single ticket and self-assembling the result into a PR.
---
2. Background: Why OpenAI Open-Sourced This
2.1 The First Dilemma
For years, OpenAI positioned Codex as a strong programmer — essentially a more capable chat assistant. But as models grew, this positioning became an agent-unfriendly constraint, lacking a programming model and guardrails.
2.2 The Second Dilemma
Agents got smarter, and work changed: parallel development.
A single Codex instance can only handle one task — code, tests, documentation, commits. A single engineer needs 3–5 such instances running simultaneously — while themselves handling strategy, code review, and communication that machines can't do.
> "They effectively need a personal program committee, not a manager. Otherwise it doesn't scale."
2.3 The Third Dilemma
OpenAI realized: the bottleneck is not the model. When coding sessions and merged PRs can correspond one-to-one, PR and session become the same thing. What's missing is a management layer built around deliverables: issue, task, milestone.
*(Note: this is not entirely new — the software industry has tried similar things for decades, often painfully.)*
---
3. Architecture Design
3.1 Ticket-First: Project as the Container
| Traditional approach | Symphony approach | |---|---| | Engineer launches N Codex instances | Every open task is scheduled to an agent | | Engineers distribute tickets | Agents claim tickets themselves | | Engineers track progress | Agents push progress to a PR |
3.2 DAG and Topology
- Agent topologies are declared by engineers, not fixed
- Topology can load dynamic DAGs (see figure)
- The DAG's execution order is the agent's execution order
- PM and colleagues submit feature requests in Linear
- Without checking out code, view the status of each Codex session
- Open the review pack (i.e., the walkthrough) to check results
- Symphony lets it bypass routine implementation work
- It directly handles error handling and edge case adaptation
- No more "constantly context-switching and struggling" — just "solve one hard problem at a time"
- Engineers deliver speculative tasks in bulk
- Review results, accept what's good, discard what's not
- Self-healing: even when a major bug appears in a Linear mobile app update, agents self-assemble to fix it
- High-capability models
- Rich, structured context
- Task decomposition and guardrails
- Measurable workflow
- Exposes a JSON-RPC API to drive execution
- More scalable than CLI or tmux snapshots
- Unified tool calls: connect the same Linear token to any agent
- checkout repo
- put in progress (PM sees status in real time)
- add PR
- move to Review
- attach videos
- Clean tickets, clear acceptance, explicit deliverable layer — routine implementation work
- Projects with existing tests and guardrails
- Tasks can be packaged as deliverables
- Error handling and edge cases
- Requiring careful judgment and expertise
- Highly cross-functional coupling and business-sensitive code
Example: a React-to-Vite migration project. The agent generates the Vite skeleton; a sub-agent writes React components.
3.3 Deliverable Layer
Every task has a shared workspace with no silos.
3.4 PR as the Process Lifecycle Boundary
| Ticket stage | Agent action | |---|---| | In Progress | Check out code | | Review | Submit PR, attach walkthrough video | | CI | Run tests, lint, type checking, unit tests | | Merging | Rebase, resolve conflicts, merge locally |
When a ticket reaches Merging, OpenAI has already solved the parallel-agent babysitting problem.
---
4. Case Studies
4.1 Video Walkthroughs
| Metric | Value | |---|---| | Cumulative landed PRs | +500% (vs baseline) | | Engineer concurrent instances | From 3–5 → 0 (all managed by Symphony scheduling) | | Engineer intervention frequency | Near zero |
4.2 Actual Operation
An engineer's day:
An agent's busy day:
Engineer intervention near zero:
---
5. Trade-offs and Failure Modes
5.1 Not a Silver Bullet
Agents still fail. OpenAI's answer is not to invent a magic patch, but a combination of:
Key insight: this is not a replacement for human engineering, but a systematic supplement.
5.2 What AI Cannot Replace Yet
Even in highly automated agent flows, engineers still need to judge implement tasks. You still have to tell Codex what to do: review feedback, modify specs, adjust PRs, fix build failures.
Conclusion: it's "letting the machine do more of the work" rather than "letting humans rest" — yet the engineers are happier, and the whole team is more efficient.
---
6. Implementation Details
6.1 Pure Markdown Format
Symphony's deliverable is SPEC.md — a Markdown file describing process and mechanisms. Any model can read and execute it, so it doubles as the model's steering file.
6.2 Cross-Model: Elixir
Borrowing Elixir's philosophy: "let failure die effectively" (error handling shouldn't consume the main process). Elixir's actor model and fault-tolerance philosophy fit multi-agent and fault-tolerant scheduling.
This idea can be extended to any language — OpenAI's Codex uses TypeScript; Go, Rust, Java, and Python can all follow the same spec template.
6.3 Version Evolution
| Version | Form | Effect | |---|---|---| | V1 | tmux plus a Codex session, echoing Linear, spawn one agent | Doesn't scale | | V2 | Project management layer (a layer of agent harness) | Supports DAG orchestration | | V3 | Standalone SPEC.md, Codex reads it | Usable, shareable |
6.4 Codex App Server Comparison
Using Codex's headless mode:
6.5 WORKFLOW.md
Encode the implicit process explicitly:
By writing WORKFLOW.md, Symphony lets agents be supervised — even self-reflect (attach self-reflection), enabling iteration.
---
7. Applicable Scenarios
7.1 What Works
7.2 What Doesn't Work
---
8. Comparison with Similar Projects
8.1 How Agents Differ
| Project | Core idea | |---|---| | Symphony | Project container orchestration, agents claim tasks | | DeerFlow 2.0 | Graph model plus multi-agent plus deep research, topology-driven | | RAO | Native LLM protocol adapter | | KohakuTerrarium | Creature + Terrarium + Studio ecosystem |
Shared premise: multi-agent collaboration needs a project-level model plus guardrails — i.e., agent self-assembly.
8.2 Design Evolution
1. Structured context: encode implicit process as WORKFLOW.md so agents can follow it
2. Layered abstraction and guardrails: agents have clear boundaries and tool whitelists — not free-for-all
3. Project model and living documents: project and document are one and the same; the document is the running system and living doc
4. Human-in-the-loop: human agent collaboration is a systematic design, not an afterthought
---
9. Closing Summary
OpenAI sums it up: Symphony is not a replacement — it's a reference implementation.
> "If you want to see what a coding agent harness engineering document scaffold should look like, treat this coding agent harness Symphony spec and run it as a learning template."
It's a companion to Codex and App Server. Symphony is just one answer for Codex and Linear.
---
10. Extended Reading
1. Process tracking: when multi-agent collaboration becomes the norm, tracking and "auditing" become new engineer capabilities 2. Concurrency is the main battlefield: engineers' futures won't be in micro-managing agents 3. Engineer intervention near zero: agents bulk-deliver speculative work, with humans as the final safety net 4. The thinking mode: agents still need thinking mode — that's the systematic entrance 5. Human > machine: manage agents and projects; humans focus on real cooking
---
References
1. OpenAI. *Symphony: Open-Sourcing Codex Orchestration*. 2026. https://openai.com/index/open-source-codex-orchestration-symphony/ 2. OpenAI. *Harness Engineering*. 2025. 3. OpenAI. *Codex App Server*. 2026. 4. Linear. https://linear.app