symphony

Symphony is an open source orchestration service from OpenAI that bridges the gap between issue tracking and autonomous code implementation. Instead of requiring engineers to supervise individual AI coding sessions, Symphony polls your Linear board, picks up eligible tickets, and dispatches isolated Codex agents to implement each one in its own workspace. Engineers interact at the project management layer—reviewing PRs, adjusting ticket states, watching proof-of-work artifacts—while Symphony handles the agent lifecycle.

The project ships as two complementary artifacts: a language-agnostic specification (SPEC.md) that defines the full orchestration contract, and a reference implementation in Elixir that brings that spec to life using OTP/GenServer concurrency, Phoenix LiveView for real-time dashboard visibility, and the Codex app-server protocol for agent communication. Teams can adopt the Elixir implementation directly or use the spec to build their own Symphony in any language.

Each ticket gets a dedicated workspace directory that persists across retries and continues work across multiple Codex turns within a single session. The WORKFLOW.md file—kept in the target repository—controls everything from the agent prompt to polling cadence, concurrency limits, and lifecycle hooks, making the orchestration policy version-controlled alongside the code it ships. Dynamic reload means configuration changes take effect without restarting the service.

Symphony is explicitly positioned as an engineering preview for trusted environments. It does not prescribe a single sandboxing or approval posture, instead requiring each implementation to document its own trust boundary. For teams already practicing harness engineering and comfortable with AI-assisted development, Symphony removes the last manual step: watching agents run.

What You Get

• A long-running orchestration daemon that continuously polls Linear and dispatches Codex agents to implement tickets without manual intervention
• Isolated per-issue workspace directories that persist across retries, enabling agents to resume work rather than starting from scratch on each attempt
• A WORKFLOW.md contract file that encodes the agent prompt, polling cadence, concurrency limits, and lifecycle hooks in the target repository
• A Phoenix LiveView real-time dashboard showing active agent sessions, retry queues, token consumption, and rate-limit status at a glance
• A language-agnostic SPEC.md that defines the full orchestration protocol so teams can implement Symphony in any language
• An optional SSH extension for dispatching agent workers to remote hosts while keeping the orchestrator local
• A linear_graphql client-side tool that gives in-session agents direct access to the Linear API using Symphony’s configured credentials

Common Use Cases

• Autonomous feature implementation where a team assigns tickets in Linear and Symphony delivers PRs with CI status and walkthrough videos as proof of work
• Parallel bug-fix pipelines where multiple Codex agents work on separate issues simultaneously under global and per-state concurrency caps
• Nightly or continuous automation runs where Symphony picks up queued work overnight and engineers review results in the morning
• Custom workflow encoding where teams embed project-specific review steps, git branching rules, and Linear state transitions directly in WORKFLOW.md
• Multi-host scale-out where SSH workers distribute agent execution across machines while the central orchestrator manages dispatch and retries
• Specification-driven porting where teams implement Symphony in Python, Go, or TypeScript using SPEC.md as the authoritative contract

Under The Hood

Architecture Symphony is built around a single-authority orchestrator that owns all mutable scheduling state—running sessions, claimed issues, retry timers, and token totals—through an Elixir GenServer process. The design deliberately avoids distributed state or persistent databases for the scheduler: recovery is tracker-driven and filesystem-driven, meaning the service regains useful operation after a restart simply by re-polling Linear and reusing preserved workspaces. Concerns are cleanly separated across six layers—policy (WORKFLOW.md), configuration (typed getters with $VAR resolution), coordination (orchestrator), execution (workspace and agent subprocess), integration (Linear adapter), and observability (structured logs plus optional Phoenix LiveView dashboard)—with each layer having a narrow, well-defined interface. The spec-first design means the Elixir implementation is one conforming instantiation of a documented protocol, not the canonical truth.

Tech Stack The reference implementation targets Elixir 1.19 on OTP, leveraging GenServer for the orchestrator event loop, Task/spawn for concurrent worker processes, and the BEAM’s lightweight process model to isolate each agent session. Phoenix 1.8 and Phoenix LiveView 1.1 power the optional web dashboard with server-push real-time updates over WebSocket without client-side JavaScript frameworks. The Bandit HTTP server handles web traffic. Liquid template rendering (via the Solid library) drives strict-variable prompt construction. The YAML Elixir library parses WORKFLOW.md front matter. The Req HTTP client handles Linear GraphQL requests. Codex agents are launched as external OS subprocesses via Port communication over stdio, following the Codex app-server JSON protocol. No database is required—all orchestrator state is in-memory.

Code Quality The test suite is comprehensive, spanning approximately 9,300 lines across thirteen test files covering orchestrator dispatch logic, workspace safety invariants, app-server protocol handling, SSH extension behavior, LiveView rendering snapshots, CLI lifecycle, and dynamic tool execution. The project targets 100% test coverage on testable modules, with explicitly listed ignore modules for IO-bound and external-process-dependent components. Credo strict-mode linting and Dialyzer type analysis are integrated into the lint pipeline. The spec check (SpecsCheck module) runs the formal SPEC.md validation matrix in CI. Error handling is typed and explicit throughout: errors return tagged tuples, the orchestrator converts all worker exits into explicit state transitions, and hook failures are mapped to distinct failure categories.

What Makes It Unique Symphony’s most distinctive property is its spec-first architecture: the project ships a formal language-agnostic specification (SPEC.md) describing the full orchestration contract before providing any reference implementation. This means teams can port Symphony to their preferred runtime without reverse-engineering Elixir code, and conformance is verifiable against a published test matrix rather than by matching runtime behavior. The WORKFLOW.md pattern—encoding the agent prompt, polling config, concurrency policy, and lifecycle hooks as a repository-owned Markdown file—is a second unusual choice: it makes the orchestration behavior a first-class artifact in the codebase, subject to code review, diff, and version history. The combination of issue-isolated workspaces that persist across retries with multi-turn Codex sessions on the same live thread (rather than restarting agents per turn) reduces redundant context rebuilding and enables genuine continuation workflows rather than mere retries.

Self-Hosting

Symphony is released under the Apache License 2.0, one of the most permissive open source licenses available. You can use it commercially, modify it, distribute it, and incorporate it into proprietary products without any copyleft obligation—meaning your WORKFLOW.md customizations, internal implementations, and derivative orchestrators do not need to be open-sourced. The only requirements are retaining license notices and the NOTICE file in distributed copies.

Running Symphony yourself means owning the entire orchestration layer. You will need a host capable of running Elixir/OTP (or your own language port), outbound access to the Linear GraphQL API, the Codex app-server executable installed in each agent’s workspace environment, and sufficient compute to handle your target concurrency. Workspace directories are per-issue and filesystem-local by default—on a single machine that is straightforward, but the SSH extension adds remote worker dispatch for scale-out at the cost of managing SSH access and ensuring each remote host has the correct environment. There is no built-in persistence layer: the orchestrator’s retry timers and active session state live in memory and are lost on restart. Recovery is intentionally tracker-driven, so this is acceptable for most workloads but means you cannot rely on Symphony surviving a crash mid-turn without re-examining Linear state.

There is no hosted or managed version of Symphony. OpenAI publishes it as an engineering preview rather than a supported product, which means there are no SLAs, no managed upgrades, no cloud backups, and no enterprise support tier. The project is explicitly marked as prototype software intended for trusted environments, and the documentation encourages teams to build their own hardened implementation from SPEC.md rather than deploying the Elixir reference as-is in production. Teams adopting Symphony in serious workflows should budget time to understand and define their own approval policies, sandbox controls, and secret-handling posture—none of which are prescribed by the spec.