# Symphony: features, protocols, quickstart

## TL;DR

Symphony is an Apache-2.0 project from OpenAI: a language-agnostic spec plus an experimental Elixir reference implementation that polls an issue tracker, makes a workspace per issue and runs Codex in app-server mode. The README calls it a low-key engineering preview for trusted environments. It suits teams that already manage work in Linear or GitHub Issues.

## Key facts

| Field | Value |
| --- | --- |
| Type | Orchestrator |
| Languages / SDKs | Elixir |
| License | Apache-2.0 |
| Pricing model | Open source, free |
| Orchestration pattern | Other |
| GitHub stars | 27,483 (as of 2026-09-30) |
| GitHub forks | 2,849 |
| Last push | 2026-09-15 |
| Latest release | v0.0.3 |
| Repository | [openai/symphony](https://github.com/openai/symphony) |
| Website | [openai.com](https://openai.com/index/open-source-codex-orchestration-symphony/) |
| Documentation | [github.com](https://github.com/openai/symphony/blob/main/SPEC.md) |
| Last verified | 2026-09-30 |

## Key features

- Polls a configured tracker for candidate issues; the Elixir implementation includes adapters for Linear, GitHub Issues, Jira Cloud, Asana and GitLab. ([source](https://github.com/openai/symphony/blob/main/elixir/README.md))
- Creates a workspace directory per issue and starts `codex app-server` inside it, sending a workflow prompt and continuing turns until the issue leaves its active state. ([source](https://github.com/openai/symphony/blob/main/elixir/README.md))
- `WORKFLOW.md` keeps policy in the repository: YAML front matter for tracker, workspace, hooks, concurrency and Codex settings, plus the Markdown prompt. ([source](https://github.com/openai/symphony/blob/main/elixir/README.md))
- The spec calls for bounded-concurrency dispatch, exponential backoff on transient failures and restart recovery from tracker and filesystem state without a database. ([source](https://github.com/openai/symphony/blob/main/SPEC.md))
- Provider-native tools (`linear_graphql`, `github_api`, `jira_rest`, `asana_api`, `gitlab_api`) run host-side with the tracker credential, which is stripped from the Codex child process. ([source](https://github.com/openai/symphony/blob/main/elixir/README.md))
- An optional Phoenix LiveView dashboard and JSON API show runtime state, including issues blocked waiting for operator input. ([source](https://github.com/openai/symphony/blob/main/elixir/README.md))
- The bundled workflow uses Linear states such as Human Review, Merging and Rework so a person approves before an agent lands the PR. ([source](https://github.com/openai/symphony/blob/main/elixir/WORKFLOW.md))

## Architecture and orchestration pattern

Pattern: Other.

Symphony is a long-running service, not a chat tool. The specification (Draft v1, language-agnostic) defines an orchestrator that reads work from an issue tracker, keeps claim and retry state, creates an isolated workspace for each issue and runs one coding-agent session per issue. Ticket writes such as state changes, comments and PR links are normally done by the agent through tracker tools that Symphony executes with the configured credential.

The Elixir/OTP reference implementation launches Codex in app-server mode with a workflow prompt. Workspaces are directories under `workspace.root`, bootstrapped by a `hooks.after_create` script (the example runs `git clone`), so isolation is per-issue checkouts plus Codex's sandbox settings. If an issue reaches a terminal state, the agent is stopped and its workspaces are cleaned up.

State lives in the running orchestrator and in the tracker: blocked entries are kept in memory only and are cleared on restart, after which active issues can be dispatched again. Coordination between agents is indirect, through the tracker's states and comments.

### Human in the loop

The bundled workflow moves a ticket to Human Review when a PR is attached and validated, waits for a person, and only runs the `land` skill after the person moves it to Merging; Rework returns it to the agent. Codex approval defaults are strict: the Elixir implementation rejects sandbox approvals, rule approvals and MCP elicitations unless configured otherwise, and if Codex reports that input or approval is required the issue is shown as blocked in the dashboard and API. Moving an issue to a terminal state stops its agent.

### Harnesses it can drive

- Codex ([evidence](https://github.com/openai/symphony/blob/main/elixir/README.md))

## Protocols

| Protocol | Support | Evidence | Note |
| --- | --- | --- | --- |
| MCP | Unknown (checked 2026-09-30) | — | No MCP client or server is documented. Related mentions only: the bundled WORKFLOW.md lets the agent use a configured Linear MCP server or the injected `linear_graphql` tool, and the Elixir app-server code treats Codex MCP elicitation requests as needing operator input. |
| A2A | Unknown (checked 2026-09-30) | — | Searched the README, SPEC.md, Elixir README and file names for 'a2a' and 'agent2agent'; nothing found. |
| AG-UI | Unknown (checked 2026-09-30) | — | Searched the README, SPEC.md and Elixir README for 'ag-ui'; nothing found. |

## Best for

- Teams whose work is already ticketed in Linear, GitHub Issues, Jira, Asana or GitLab and who want Codex to pick up tickets automatically. ([shortlist](https://multiagentguide.top/best/parallel-coding-agents.md))
- Running several ticket-scoped Codex sessions concurrently with a human approval state before merge. ([shortlist](https://multiagentguide.top/best/parallel-coding-agents.md))
- Teams that want a written spec to reimplement in their own language and harden themselves. ([shortlist](https://multiagentguide.top/best/coding-agents.md))

## Not for

- Production use as-is: the Elixir README calls it prototype software for evaluation, and the top-level README says it is for trusted environments.
- Teams using Claude Code, OpenCode or other agents: the reference implementation launches Codex only.
- Interactive, hands-on pairing with an agent; Symphony is a background scheduler driven by tracker states.

## Quickstart

```sh
git clone https://github.com/openai/symphony
cd symphony/elixir
mise trust
mise install
mise exec -- mix setup
mise exec -- mix build
mise exec -- ./bin/symphony ./WORKFLOW.md
```

Install not yet verified by this site.

```bash
# Prerequisites: mise (Elixir/Erlang), codex, git, and a tracker token
export LINEAR_API_KEY=...          # Linear personal API key
git clone https://github.com/openai/symphony
cd symphony/elixir
mise trust && mise install
mise exec -- mix setup && mise exec -- mix build

# WORKFLOW.md (copied into your repo) starts with YAML front matter like:
#   tracker: {kind: linear, provider: {project_slug: "..."}}
#   workspace: {root: ~/code/workspaces}
#   hooks: {after_create: "git clone git@github.com:your-org/your-repo.git ."}
#   agent: {max_concurrent_agents: 10, max_turns: 20}
#   codex: {command: codex app-server}
mise exec -- ./bin/symphony ./WORKFLOW.md --port 4000   # --port enables the dashboard
```

### Common pitfalls

- Symphony Elixir is prototype software for evaluation; the README recommends implementing your own hardened version from SPEC.md, and the top-level README says trusted environments only.
- The bundled workflow depends on non-standard Linear statuses (Rework, Human Review, Merging) that you must create in Team Settings.
- The `codex`, `git` and tracker credentials must be present on the host, including with the Burrito executables.
- Workflows that run package managers need `networkAccess: true` in `codex.turn_sandbox_policy`, otherwise the Codex turn sandbox may deny DNS.
- If `WORKFLOW.md` is missing or has invalid YAML at startup, Symphony does not boot; a later invalid reload keeps the last good workflow.
- Blocked entries are in memory only, so a restart can make still-active issues dispatch candidates again.

Official quickstart: https://github.com/openai/symphony/blob/main/elixir/README.md

## Pros

- Manages work at the ticket level: agents get their own workspace per issue and proof of work is expected before a human approves. ([source](https://github.com/openai/symphony/blob/main/README.md))
- Language-agnostic spec lets teams write their own implementation, alongside the Elixir reference. ([source](https://github.com/openai/symphony/blob/main/SPEC.md))
- Safer Codex defaults: workspace-write sandbox and approval requests rejected unless configured. ([source](https://github.com/openai/symphony/blob/main/elixir/README.md))
- Five tracker adapters, with tracker credentials kept out of the Codex child process. ([source](https://github.com/openai/symphony/blob/main/elixir/README.md))
- Apache-2.0 licensed under the openai organization, with Burrito executables for macOS and Linux (arm64 and x86_64). ([source](https://github.com/openai/symphony/blob/main/elixir/README.md))

## Cons

- OpenAI calls it a low-key engineering preview for trusted environments, and the Elixir implementation prototype software for evaluation only. ([source](https://github.com/openai/symphony/blob/main/README.md))
- The reference implementation is tied to Codex app-server; other agents need your own implementation. ([source](https://github.com/openai/symphony/blob/main/elixir/README.md))
- Tracker tools run with the configured token's full permissions; `project_slug` scopes scheduling reads, not raw tool calls. ([source](https://github.com/openai/symphony/blob/main/elixir/README.md))
- Blocked-issue state is memory-only and cleared on restart. ([source](https://github.com/openai/symphony/blob/main/elixir/README.md))
- Release versions are 0.0.x (v0.0.3 on 2026-09-15), so interfaces may change. ([source](https://github.com/openai/symphony/releases))

## Alternatives

- [Vibe Kanban](https://multiagentguide.top/tools/vibe-kanban.md)
- [Multica](https://multiagentguide.top/tools/multica.md) ([Symphony vs Multica](https://multiagentguide.top/compare/multica-vs-symphony.md))
- [Codex CLI](https://multiagentguide.top/tools/codex.md)
- [OpenHands](https://multiagentguide.top/tools/openhands.md)
- [Gas Town](https://multiagentguide.top/tools/gastown.md)

## FAQ

### Does Symphony support MCP?

No MCP client or server is documented for Symphony itself, so the record marks it unknown. The bundled workflow lets the agent use a Linear MCP server if one is configured, and MCP elicitation requests from Codex are treated as needing operator input.

### Which coding agents does it run?

The Elixir reference implementation starts Codex in app-server mode. The spec describes a generic coding-agent session, so other agents would need your own implementation.

### Is Symphony free?

The code is Apache-2.0 and no paid product is documented. Running it uses your own Codex and tracker accounts.

### Does it use git worktrees?

Not in the docs read. It creates a workspace directory per issue and the example hook runs `git clone` into it; the repository's `.codex/worktree_init.sh` only sets up the Elixir project for development.

### Is it ready for production?

OpenAI describes it as a low-key engineering preview for trusted environments, and the Elixir README recommends implementing your own hardened version from SPEC.md.

## Sources

- [Symphony GitHub repository](https://github.com/openai/symphony)
- [Symphony README](https://github.com/openai/symphony/blob/main/README.md)
- [Symphony Elixir README](https://github.com/openai/symphony/blob/main/elixir/README.md)
- [Symphony service specification (SPEC.md)](https://github.com/openai/symphony/blob/main/SPEC.md)
- [Bundled WORKFLOW.md](https://github.com/openai/symphony/blob/main/elixir/WORKFLOW.md)
- [Symphony announcement (repository homepage link)](https://openai.com/index/open-source-codex-orchestration-symphony/)
- [Symphony releases](https://github.com/openai/symphony/releases)

## Unknown fields

protocols.mcp, a2a, agui: no protocol support documented; MCP appears only in the bundled workflow and Codex elicitation handling. The OpenAI announcement page returned 403 to the fetcher and was not read; nothing in this record is taken from it. Whether the spec describes agents other than Codex beyond a generic coding-agent session was not fully verified. docs_url points to SPEC.md because the project has no docs site.

Corrections or removal requests: support@multiagentguide.top

---

Data as of 2026-09-30. Not affiliated with listed projects. HTML version: https://multiagentguide.top/tools/symphony