# OpenAI Symphony: Orchestrating AI Coding Agents with an Issue Tracker [Symphony](https://github.com/openai/symphony) is an **open-source specification from OpenAI for orchestrating AI coding agents**. Rather than requiring developers to manually manage agent sessions, Symphony connects an issue tracker to a fleet of agents: **it polls the tracker, identifies ready tasks, creates isolated workspaces, dispatches an agent to each,** and updates the issue when work is complete. The human engineer is brought into the loop for review rather than constant supervision. ## The orchestration model ![OpenAI blog snippet highlighting the "bottleneck: human attention" problem explaining that engineers became micromanagers for AI agents](https://imagedelivery.net/xZXo0QFi-1_4Zimer-T0XQ/c52d4a77-a7bc-4cd9-5283-1a58ce854c00/lg2x =1920x1080) The human attention bottleneck that motivated Symphony was simple: developers could manage three to five concurrent agent sessions before context switching between terminals, task statuses, and agent states became unmanageable. The fix is to shift focus from managing agents to managing a queue of work. The workflow Symphony enables: 1. A developer creates a detailed issue in Linear or a similar tracker. 2. Symphony polls the tracker, detects the issue, and creates an isolated workspace for it. 3. A coding agent (Codex, Claude, or any capable agent) is dispatched to the workspace with the task context. 4. The agent writes code, runs tests, and produces artifacts autonomously. 5. Symphony updates the issue and optionally creates a pull request. The developer reviews the result. ## Core components **`SPEC.md`** is the authoritative definition of how a Symphony orchestrator should behave: required components, their interactions, and data structures. It is the blueprint that any implementation must follow. **The orchestrator** is the running process that polls the tracker, manages workspaces, dispatches agents, and monitors progress. **The issue tracker** is the source of truth for work. Symphony is designed to integrate with Linear, Jira, or similar tools. It reads task details and updates state on completion. **The coding agent** performs the work. Symphony is agent-agnostic; any capable coding agent can be plugged in. **Workspaces** are temporary, isolated directories created per task. Each agent works in its own sandbox. **`WORKFLOW.md`** is the primary configuration file. It is a YAML front-matter document specifying the tracker connection, agent command, workspace location, and hooks. ## Two ways to get started ![Symphony README on GitHub showing the two options: "Make your own" and "Use our experimental reference implementation"](https://imagedelivery.net/xZXo0QFi-1_4Zimer-T0XQ/8e44a13a-512a-4d88-2864-747f3bb69d00/public =1920x1080) **Option 1: generate an implementation from the spec.** Feed the specification URL to a coding agent and ask it to implement Symphony: ```text Implement Symphony according to the following spec: https://github.com/openai/symphony/blob/main/SPEC.md ``` The agent reads the specification and generates a complete implementation in the language you specify. The resulting code is fully owned and customizable. This approach produces an implementation in whatever language fits the team's stack, and maintenance responsibility rests with whoever generated it. ![Terminal showing the prompt being given to the OpenAI Codex agent which then confirms it will pull the spec and build the implementation](https://imagedelivery.net/xZXo0QFi-1_4Zimer-T0XQ/6e243b33-bdcf-42fa-0210-80f8b3f96900/public =1920x1080) **Option 2: use the Elixir reference implementation.** Clone the repository and follow the build instructions in the `elixir` directory. This is appropriate for getting started quickly without generating an implementation. ```command git clone https://github.com/openai/symphony ``` ## Basic workflow configuration A `WORKFLOW.md` file configures the orchestrator. Below is a minimal Linear integration: ```yaml [label WORKFLOW.md] --- tracker: kind: linear api_key: $LINEAR_API_KEY team_key: SYN done_state: Done active_states: - Todo - In Progress workspace: root: ./symphony_workspaces agent: max_concurrent_agents: 1 codex: command: codex --sandbox workspace-write --ask-for-approval never exec --skip-git-repo-check --- You are working on Linear issue {{ issue.identifier }}: {{ issue.title }} Description: {{ issue.description }} Work in the issue workspace prepared by Symphony. Follow the repository's existing conventions, make focused changes, validate them, and leave the issue ready for human review. ``` The `tracker` section specifies the integration type, API key (read from an environment variable), and which issue states Symphony should pick up. The `codex` section defines the shell command for the agent. The Markdown body after the `---` separator is a prompt template; `{{ issue.title }}` and similar placeholders are replaced with actual issue data at runtime. ## Running Symphony Start the orchestrator pointing to the workflow file: ```command uv run python -m symphony.cli --workflow WORKFLOW.md ``` When a Linear issue in an active state is detected, Symphony logs a `worker_dispatched` event, runs the agent, and logs `worker_completed` when the agent finishes. The issue moves to the done state automatically. ![Linear Kanban board showing the "Hello World App" task automatically moved to the "Done" column after the agent completed its work](https://imagedelivery.net/xZXo0QFi-1_4Zimer-T0XQ/550a5453-9e2a-45e2-1db9-dd76c7928100/lg2x =1920x1080) Each completed task creates a subdirectory under `symphony_workspaces` named with the issue identifier containing the agent's output. ## Git-integrated workflow with hooks For work on existing repositories, hooks extend the workflow with commands that run at specific lifecycle points. - `after_create`: runs immediately after the workspace directory is created - `after_run`: runs after the agent completes its work The following hooks clone a repository into the workspace, create a branch, commit the agent's changes, push, and open a pull request: ```yaml [label WORKFLOW.md] hooks: after_create: | gh repo clone Your-Org/your-repo . git checkout -B symphony/{{ issue.identifier }} after_run: | git add . git diff --cached --quiet || git commit -m "{{ issue.identifier }}: {{ issue.title }}" git push -u origin symphony/{{ issue.identifier }} gh pr create \ --title "{{ issue.identifier }}: {{ issue.title }}" \ --body "Linear: {{ issue.url }}" ``` `after_create` clones the repository into the workspace and creates a uniquely named branch using the issue identifier. `after_run` stages all changes, creates a commit only if there are staged changes (the `git diff --cached --quiet ||` guard prevents empty commits), pushes the branch, and opens a pull request with the issue title and a link back to the Linear ticket. ![GitHub pull request screen showing a new PR created by the Symphony after_run hook with title and body linking back to the original Linear issue](https://imagedelivery.net/xZXo0QFi-1_4Zimer-T0XQ/70e181a0-3e7b-40d4-2190-00afb62d9b00/lg1x =1920x1080) With this configuration, creating a Linear issue like "Refactor the authentication service" triggers the full development lifecycle: branch creation, agent work, commit, push, and pull request. The developer reviews the PR. ## Final thoughts Symphony is an orchestration pattern more than a fixed tool. The **spec-driven distribution model is unusual: by publishing a specification and encouraging teams to generate their own implementation**, OpenAI shifts customization and maintenance to the teams that use it. An implementation generated in Python for one team, Go for another, and TypeScript for a third can each be tailored to the team's existing infrastructure and conventions. The practical value is in reducing the supervisory overhead of running many agents in parallel. Issue trackers become the interface for directing agent work, and the orchestrator handles the mechanical parts of workspace creation, task dispatch, and status updates. The specification, reference implementation, and documentation are at [github.com/openai/symphony](https://github.com/openai/symphony).