OpenAI Symphony: Orchestrating AI Coding Agents with an Issue Tracker

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

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

Option 1: generate an implementation from the spec. Feed the specification URL to a coding agent and ask it to implement Symphony:

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.

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.

git clone https://github.com/openai/symphony

Basic workflow configuration

A WORKFLOW.md file configures the orchestrator. Below is a minimal Linear integration:

---
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:

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.

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:

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.

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.

Got an article suggestion? Let us know

This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.