Openai Symphony Autonomous Agents

1---2name: openai-symphony-autonomous-agents3description: Symphony turns project work into isolated, autonomous implementation runs, allowing teams to manage work instead of supervising coding agents.4triggers:5  - set up Symphony for my repository6  - run autonomous coding agents on my project7  - integrate Symphony with Linear board8  - manage work with coding agents instead of supervising them9  - implement Symphony spec in my codebase10  - spawn isolated agent runs for tasks11  - configure Symphony Elixir implementation12  - automate PR workflow with Symphony agents13---14 15# OpenAI Symphony16 17> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.18 19Symphony turns project work into isolated, autonomous implementation runs, allowing teams to **manage work** instead of **supervising coding agents**. Instead of watching an agent code, you define tasks (e.g. in Linear), and Symphony spawns agents that complete them, provide proof of work (CI status, PR reviews, walkthrough videos), and land PRs autonomously.20 21---22 23## What Symphony Does24 25- Monitors a work tracker (e.g. Linear) for tasks26- Spawns isolated agent runs per task (using Codex or similar)27- Each agent implements the task, opens a PR, and provides proof of work28- Engineers review outcomes, not agent sessions29- Works best in codebases using [harness engineering](https://openai.com/index/harness-engineering/)30 31---32 33## Installation Options34 35### Option 1: Ask an agent to build it36 37Paste this prompt into Claude Code, Cursor, or Codex:38 39```40Implement Symphony according to the following spec:41https://github.com/openai/symphony/blob/main/SPEC.md42```43 44### Option 2: Use the Elixir reference implementation45 46```bash47git clone https://github.com/openai/symphony.git48cd symphony/elixir49```50 51Follow `elixir/README.md`, or ask an agent:52 53```54Set up Symphony for my repository based on55https://github.com/openai/symphony/blob/main/elixir/README.md56```57 58---59 60## Elixir Reference Implementation Setup61 62### Requirements63 64- Elixir + Mix installed65- An OpenAI API key (for Codex agent)66- A Linear API key (if using Linear integration)67- A GitHub token (for PR operations)68 69### Environment Variables70 71```bash72export OPENAI_API_KEY="sk-..."           # OpenAI API key for Codex73export LINEAR_API_KEY="lin_api_..."      # Linear integration74export GITHUB_TOKEN="ghp_..."           # GitHub PR operations75export SYMPHONY_REPO_PATH="/path/to/repo"  # Target repository76```77 78### Install Dependencies79 80```bash81cd elixir82mix deps.get83```84 85### Configuration (`elixir/config/config.exs`)86 87```elixir88import Config89 90config :symphony,91  openai_api_key: System.get_env("OPENAI_API_KEY"),92  linear_api_key: System.get_env("LINEAR_API_KEY"),93  github_token: System.get_env("GITHUB_TOKEN"),94  repo_path: System.get_env("SYMPHONY_REPO_PATH", "./"),95  poll_interval_ms: 30_000,96  max_concurrent_agents: 397```98 99### Run Symphony100 101```bash102mix symphony.start103# or in IEx for development104iex -S mix105```106 107---108 109## Core Concepts110 111### Isolated Implementation Runs112 113Each task gets its own isolated run:114- Fresh git branch per task115- Agent operates only within that branch116- No shared state between runs117- Proof of work collected before PR merge118 119### Proof of Work120 121Before a PR is accepted, Symphony collects:122- CI/CD pipeline status123- PR review feedback124- Complexity analysis125- (optionally) walkthrough videos126 127---128 129## Key Elixir Modules & Patterns130 131### Starting the Symphony supervisor132 133```elixir134# In your application.ex or directly135defmodule MyApp.Application do136  use Application137 138  def start(_type, _args) do139    children = [140      Symphony.Supervisor141    ]142    Supervisor.start_link(children, strategy: :one_for_one)143  end144end145```146 147### Defining a Task (Symphony Task struct)148 149```elixir150defmodule Symphony.Task do151  @type t :: %__MODULE__{152    id: String.t(),153    title: String.t(),154    description: String.t(),155    source: :linear | :manual,156    status: :pending | :running | :completed | :failed,157    branch: String.t() | nil,158    pr_url: String.t() | nil,159    proof_of_work: map() | nil160  }161 162  defstruct [:id, :title, :description, :source,163             status: :pending, branch: nil,164             pr_url: nil, proof_of_work: nil]165end166```167 168### Spawning an Agent Run169 170```elixir171defmodule Symphony.AgentRunner do172  @doc """173  Spawns an isolated agent run for a given task.174  Each run gets its own branch and Codex session.175  """176  def run(task) do177    branch = "symphony/#{task.id}-#{slugify(task.title)}"178 179    with :ok <- Git.create_branch(branch),180         {:ok, result} <- Codex.implement(task, branch),181         {:ok, pr_url} <- GitHub.open_pr(branch, task),182         {:ok, proof} <- ProofOfWork.collect(pr_url) do183      {:ok, %{task | status: :completed, pr_url: pr_url, proof_of_work: proof}}184    else185      {:error, reason} -> {:error, reason}186    end187  end188 189  defp slugify(title) do190    title191    |> String.downcase()192    |> String.replace(~r/[^a-z0-9]+/, "-")193    |> String.trim("-")194  end195end196```197 198### Linear Integration — Polling for Tasks199 200```elixir201defmodule Symphony.Linear.Poller do202  use GenServer203 204  @poll_interval Application.compile_env(:symphony, :poll_interval_ms, 30_000)205 206  def start_link(opts \\ []) do207    GenServer.start_link(__MODULE__, opts, name: __MODULE__)208  end209 210  def init(_opts) do211    schedule_poll()212    {:ok, %{processed_ids: MapSet.new()}}213  end214 215  def handle_info(:poll, state) do216    case Symphony.Linear.Client.fetch_todo_tasks() do217      {:ok, tasks} ->218        new_tasks = Enum.reject(tasks, &MapSet.member?(state.processed_ids, &1.id))219        Enum.each(new_tasks, &Symphony.AgentRunner.run/1)220        new_ids = Enum.reduce(new_tasks, state.processed_ids, &MapSet.put(&2, &1.id))221        schedule_poll()222        {:noreply, %{state | processed_ids: new_ids}}223 224      {:error, reason} ->225        Logger.error("Linear poll failed: #{inspect(reason)}")226        schedule_poll()227        {:noreply, state}228    end229  end230 231  defp schedule_poll do232    Process.send_after(self(), :poll, @poll_interval)233  end234end235```236 237### Linear API Client238 239```elixir240defmodule Symphony.Linear.Client do241  @linear_api "https://api.linear.app/graphql"242 243  def fetch_todo_tasks do244    query = """245    query {246      issues(filter: { state: { name: { eq: "Todo" } } }) {247        nodes {248          id249          title250          description251        }252      }253    }254    """255 256    case HTTPoison.post(@linear_api, Jason.encode!(%{query: query}), headers()) do257      {:ok, %{status_code: 200, body: body}} ->258        tasks =259          body260          |> Jason.decode!()261          |> get_in(["data", "issues", "nodes"])262          |> Enum.map(&to_task/1)263        {:ok, tasks}264 265      {:error, reason} ->266        {:error, reason}267    end268  end269 270  defp headers do271    [272      {"Authorization", System.get_env("LINEAR_API_KEY")},273      {"Content-Type", "application/json"}274    ]275  end276 277  defp to_task(%{"id" => id, "title" => title, "description" => desc}) do278    %Symphony.Task{id: id, title: title, description: desc, source: :linear}279  end280end281```282 283### Proof of Work Collection284 285```elixir286defmodule Symphony.ProofOfWork do287  @doc """288  Collects proof of work for a PR before it can be merged.289  Returns a map with CI status, review feedback, and complexity.290  """291  def collect(pr_url) do292    with {:ok, ci_status} <- wait_for_ci(pr_url),293         {:ok, reviews} <- fetch_reviews(pr_url),294         {:ok, complexity} <- analyze_complexity(pr_url) do295      {:ok, %{296        ci_status: ci_status,297        reviews: reviews,298        complexity: complexity,299        collected_at: DateTime.utc_now()300      }}301    end302  end303 304  defp wait_for_ci(pr_url, retries \\ 30) do305    case GitHub.get_pr_ci_status(pr_url) do306      {:ok, :success} -> {:ok, :success}307      {:ok, :pending} when retries > 0 ->308        Process.sleep(60_000)309        wait_for_ci(pr_url, retries - 1)310      {:ok, status} -> {:ok, status}311      {:error, reason} -> {:error, reason}312    end313  end314 315  defp fetch_reviews(pr_url), do: GitHub.get_pr_reviews(pr_url)316  defp analyze_complexity(pr_url), do: GitHub.get_pr_diff_complexity(pr_url)317end318```319 320---321 322## Implementing the SPEC.md (Custom Implementation)323 324When building Symphony in another language, the spec defines:325 3261. **Task Source** — poll Linear/GitHub/Jira for tasks in a specific state3272. **Agent Invocation** — call Codex (or another agent) with task context3283. **Isolation** — each run on a fresh branch, containerized if possible3294. **Proof of Work** — CI, review, and analysis before merge3305. **Landing** — auto-merge or present to engineer for approval331 332Minimal implementation loop in pseudocode:333 334```elixir335# Core symphony loop336def symphony_loop(state) do337  tasks = fetch_new_tasks(state.source)338 339  tasks340  |> Enum.filter(&(&1.status == :todo))341  |> Enum.each(fn task ->342    Task.async(fn ->343      branch = create_isolated_branch(task)344      invoke_agent(task, branch)         # Codex / Claude / etc.345      proof = collect_proof_of_work(branch)346      present_for_review(task, proof)347    end)348  end)349 350  Process.sleep(state.poll_interval)351  symphony_loop(state)352end353```354 355---356 357## Common Patterns358 359### Limiting Concurrent Agent Runs360 361```elixir362defmodule Symphony.AgentPool do363  use GenServer364 365  @max_concurrent 3366 367  def start_link(_), do: GenServer.start_link(__MODULE__, %{running: 0, queue: []}, name: __MODULE__)368 369  def submit(task) do370    GenServer.cast(__MODULE__, {:submit, task})371  end372 373  def handle_cast({:submit, task}, %{running: n} = state) when n < @max_concurrent do374    spawn_agent(task)375    {:noreply, %{state | running: n + 1}}376  end377 378  def handle_cast({:submit, task}, %{queue: q} = state) do379    {:noreply, %{state | queue: q ++ [task]}}380  end381 382  def handle_info({:agent_done, _result}, %{running: n, queue: [next | rest]} = state) do383    spawn_agent(next)384    {:noreply, %{state | running: n, queue: rest}}385  end386 387  def handle_info({:agent_done, _result}, %{running: n} = state) do388    {:noreply, %{state | running: n - 1}}389  end390 391  defp spawn_agent(task) do392    parent = self()393    spawn(fn ->394      result = Symphony.AgentRunner.run(task)395      send(parent, {:agent_done, result})396    end)397  end398end399```400 401### Manual Task Injection (No Linear)402 403```elixir404# In IEx or a Mix task405Symphony.AgentPool.submit(%Symphony.Task{406  id: "manual-001",407  title: "Add rate limiting to API",408  description: "Implement token bucket rate limiting on /api/v1 endpoints",409  source: :manual410})411```412 413---414 415## Troubleshooting416 417| Problem | Likely Cause | Fix |418|---|---|---|419| Agents not spawning | Missing `OPENAI_API_KEY` | Check env var is exported |420| Linear tasks not detected | Wrong Linear state filter | Update query filter to match your board's state name |421| PRs not opening | Missing `GITHUB_TOKEN` or wrong repo | Verify token has `repo` scope |422| CI never completes | Timeout too short | Increase `retries` in `wait_for_ci/2` |423| Too many concurrent runs | Default pool size | Set `max_concurrent_agents` in config |424| Branch conflicts | Agent reusing branch names | Ensure task IDs are unique per run |425 426### Debug Mode427 428```elixir429# In config/dev.exs430config :symphony, log_level: :debug431 432# Or at runtime433Logger.put_module_level(Symphony.AgentRunner, :debug)434Logger.put_module_level(Symphony.Linear.Poller, :debug)435```436 437---438 439## Resources440 441- [SPEC.md](https://github.com/openai/symphony/blob/main/SPEC.md) — Full Symphony specification442- [elixir/README.md](https://github.com/openai/symphony/blob/main/elixir/README.md) — Elixir setup guide443- [Harness Engineering](https://openai.com/index/harness-engineering/) — Prerequisite methodology444- [Apache 2.0 License](https://github.com/openai/symphony/blob/main/LICENSE)