Symphony

What Symphony Does

Symphony is an open-source orchestration service from OpenAI that turns issue tracker tickets into autonomous coding agent runs. It continuously polls Linear for eligible issues, creates isolated per-issue workspaces, and launches a coding agent session for each one. The agent works the issue — writing code, running tests, opening PRs — and Symphony tracks progress, handles retries, and cleans up when done.

The key insight: engineers manage work (issues), not agents. Symphony handles the translation from "ticket in backlog" to "PR in review."

Category: Autonomous Agentic Engineering Tools

---

How It Works

Architecture

Symphony has six core components:

1. Workflow Loader — Reads WORKFLOW.md from the repo (YAML front matter + prompt body)
2. Config Layer — Typed getters for workflow config with defaults and env var indirection
3. Issue Tracker Client — Fetches and normalizes issues from Linear
4. Orchestrator — Owns the poll loop, dispatch decisions, concurrency, retries, and reconciliation
5. Workspace Manager — Creates and manages per-issue directories with lifecycle hooks
6. Agent Runner — Builds prompts from issue + workflow template, launches the coding agent

Optional: a Status Surface for operator visibility and structured logging.

The WORKFLOW.md Contract

All orchestration policy lives in a single file checked into the repo:

---
tracker:
  kind: linear
  team_key: ENG
  active_states: ["In Progress", "Todo"]
  terminal_states: ["Done", "Cancelled"]
workspace:
  root: ./workspaces
concurrency:
  max_sessions: 3
agent:
  executable: codex
  timeout_minutes: 60
---

You are working on issue {{identifier}}: {{title}}

{{description}}

Follow the project's AGENTS.md for coding conventions...

This means workflow behavior is version-controlled — teams review and iterate on agent instructions the same way they review code.

Execution Flow

1. Poll — Fetch eligible issues from Linear on a fixed cadence
2. Filter — Check state eligibility, blocked-by dependencies, label filters
3. Dispatch — Create workspace, build prompt, launch agent (up to concurrency limit)
4. Monitor — Stream agent updates, track session metrics
5. Reconcile — On each tick, check if issue state changed externally (e.g., cancelled)
6. Complete — Agent finishes at a handoff state (e.g., "Human Review"), workspace preserved

Important Boundary

Symphony is explicitly a scheduler/runner, not a ticket manager. The coding agent itself handles ticket writes (state transitions, comments, PR links) using tools in its runtime environment.

---

Technical Details

Attribute	Detail
Language	Elixir (reference implementation)
License	Apache 2.0
GitHub Stars	~13K
Issue Tracker	Linear (v1 spec)
Agent Protocol	JSON-RPC app-server mode over stdio
Concurrency	Configurable max sessions
State	In-memory (restart recovery from filesystem)
Workspaces	Isolated per-issue directories
Database	None required (filesystem-based)

Retry & Recovery

• Exponential backoff on transient failures
• Restart recovery without persistent database (reconciles from filesystem + tracker state)
• Stops active runs when issue state changes make them ineligible

What It Doesn't Do

• No web UI or multi-tenant control plane
• No built-in sandboxing or approval gates
• No distributed job scheduling
• No ticket/PR management logic (that's the agent's job)
• No mandated security posture — implementations define their own trust model

---

Harness Engineering Philosophy

Symphony builds on OpenAI's concept of harness engineering — the idea that the most effective way to work with coding agents is to invest in your repo's structure:

• Strong CI/CD pipelines that agents can run against
• Clear AGENTS.md / WORKFLOW.md conventions
• Good test coverage agents can validate against
• Documentation that serves as agent context

The better your repo's "harness," the more autonomously agents can operate. Symphony is the next step: moving from managing coding agents to managing work that needs to get done.

---

Strengths

• Issue-tracker-driven — Natural integration with existing engineering workflows (Linear)
• In-repo policy — WORKFLOW.md keeps agent behavior versioned and reviewable
• Workspace isolation — Each issue gets its own directory, preventing cross-contamination
• Lightweight — No database, no web UI, just a daemon that reads issues and runs agents
• OpenAI backing — From the Codex team, designed to work well with Codex
• 13K stars in 3 weeks — Strong community signal

Limitations

• Linear-only — v1 spec only supports Linear; no GitHub Issues, Jira, or other trackers
• Single-agent per issue — No multi-agent collaboration within an issue (unlike Gastown or Metaswarm)
• No quality gates — No cross-model review, coverage enforcement, or blocking gates
• Elixir-only reference — Spec encourages reimplementation, but only Elixir ships today
• Engineering preview — Explicitly not production-ready; designed for "trusted environments"
• No sandboxing — Agents run with whatever permissions the host OS provides
• Codex-oriented — JSON-RPC app-server protocol currently best supported by Codex

---

Competitive Context

Dimension	Symphony	Gastown	Metaswarm	Agent Orchestrator
Trigger	Issue tracker (Linear)	Manual / tmux	GitHub Issues (BEADS)	GitHub Issues
Multi-agent	No (1 agent/issue)	Yes (20-30)	Yes (18 agents)	Yes (parallel)
Quality gates	None	Merge queue	Cross-model review	Auto CI fix
Policy config	WORKFLOW.md	In-code	BEADS + prompts	Plugin config
Complexity	Low	High	High	Medium
Agent support	Codex (JSON-RPC)	Claude Code	Claude Code	Claude/Codex/Aider

Symphony occupies a unique niche: the simplest path from "issue in tracker" to "agent working on it." It trades multi-agent sophistication for operational simplicity.

---

Who Should Use Symphony

Good fit:

• Teams already using Linear who want to automate issue execution
• OpenAI Codex users looking for orchestration
• Organizations adopting "harness engineering" practices
• Teams that want version-controlled agent workflow configuration

Not a fit:

• Teams needing multi-agent collaboration on single issues
• Organizations requiring built-in security/sandboxing
• Teams using Jira, GitHub Issues, or other non-Linear trackers
• Production environments requiring approval gates

---

Bottom Line

Symphony is OpenAI's answer to "what comes after coding agents?" — not better agents, but better orchestration of agents around existing work. By connecting Linear issues to Codex sessions through a simple daemon with in-repo configuration, it removes the operational overhead of running autonomous agents. The 13K-star reception in three weeks confirms demand for this pattern.

The limitation is scope: Linear-only, single-agent-per-issue, no quality gates. For teams that need multi-agent orchestration, cross-model review, or enterprise security, look at Metaswarm, Gastown, or Tembo. But for teams that want the simplest path from issue tracker to autonomous execution, Symphony is the new baseline.

---

Research by Ry Walker Research • methodology