Without Symphony

• You open a ticket: "Fix the login bug"
• You manually start a coding agent
• You watch it work, approve file changes
• You check if it finished correctly
• You start the next ticket... repeat

With Symphony

• You write tickets on a board (Linear)
• Symphony sees the tickets automatically
• It assigns an agent to each one
• Agents work in parallel, in isolation
• You review PRs when they are ready

Restaurant

• Orders come in from the dining room
• Head chef reads and assigns them
• Each cook works at their own station
• If a dish fails, chef says "try again"
• Finished dishes go to the pass

Symphony

• Linear tickets appear on the board
• Orchestrator polls and dispatches them
• Each Codex agent gets its own workspace
• On failure, Symphony retries with backoff
• Completed work becomes a pull request

openai/symphony/
SPEC.md          # Language-agnostic spec
README.md        # Overview + setup
LICENSE          # Apache 2.0
elixir/
  WORKFLOW.md    # Config + agent prompt
  AGENTS.md     # Coding guidelines
  lib/
    orchestrator.ex
    agent_runner.ex
    workspace.ex
    codex/app_server.ex
    codex/dynamic_tool.ex
    linear/client.ex
    config/schema.ex
    ... + web dashboard
.codex/skills/   # commit, push, land...

Two-Layer Design

Primary language: Elixir · Web: Phoenix LiveView · Agent protocol: JSON-RPC 2.0 over stdio

Internal Claim States

Prevents duplicate dispatch — an issue can only have one active agent.

Linear Issue States (Default)

When an issue reaches a terminal state, Symphony kills the agent and removes the workspace.

Session Lifecycle

// 1. Start process
bash -lc "codex app-server"

// 2. Initialize
→ { "method": "initialize", "id": 1 }
← { "id": 1, "result": {...} }

// 3. Start thread (persists across turns)
→ { "method": "thread/start", "id": 2 }
← { "id": 2, "result": { "threadId": "..." } }

// 4. Start turn (one per iteration)
→ { "method": "turn/start", "id": 3 }
← stream of events...
← { "method": "turn/completed" }

Turn Events

Approval Handling

Approval requests for file changes and command execution are auto-approved with acceptForSession. User input requests get a canned "non-interactive session" response.

Multi-Turn Loop

Same threadId reused across continuation turns. Up to max_turns (default 20) per session.

Lifecycle Hooks

# Workspace is created
after_create:
  git clone --depth 1 \
    git@github.com:org/repo.git .

# Before agent starts
before_run:
  git fetch origin main

# After agent finishes
after_run:
  make test

# Before workspace removal
before_remove:
  mix workspace.before_remove

Safety Invariants

• Agent CWD is always the workspace path, never the source repo
• Workspace key: identifier sanitized to [A-Za-z0-9._-]
• Path validated via canonical resolution — prevents symlink escapes
• Must remain under workspace.root
• Hook timeout: 60s default

Sandbox Policies

Continuation Retry

• Delay: 1 second
• Attempt counter: 1
• Preserves workspace and host affinity
• Same thread ID continues the conversation

Failure Retry

• Formula: min(10s * 2^(attempt-1), max_backoff)
• Default max backoff: 300 seconds (5 min)
• Example: 10s, 20s, 40s, 80s, 160s, 300s, 300s...
• Prefers same worker host for retry

How It Works

When Codex sends an item/tool/call message, Symphony intercepts and executes it server-side.

// Agent sends:
{
  "method": "item/tool/call",
  "params": {
    "name": "linear_graphql",
    "arguments": {
      "query": "mutation { issueUpdate(id: $id, input: { stateId: $stateId }) { success } }",
      "variables": { ... }
    }
  }
}

Security Model

• Uses Symphony's Linear API key — never exposed to the agent
• Rejects multi-operation queries
• Returns success/failure + full GraphQL response
• Enables agents to update tickets, add comments, change status

Agent Capabilities via Tools

• Move issues to "Human Review" when done
• Post progress comments (workpad pattern)
• Query blocking issues
• Mark issues as Done/Cancelled

Available Variables

Strict Template Engine

Initial vs. Continuation Prompts

First turn gets the full rendered prompt. Continuation turns get a shorter prompt indicating "continue where you left off" with updated attempt counter.

Hot Reload

Edit WORKFLOW.md while running. New prompt applies to future runs. Invalid edits keep the last-known-good config.

Token Tracking

• Extracts usage from Codex event payloads
• Computes deltas to prevent double-counting
• Tracks input tokens, output tokens, total
• Aggregates per-session and per-orchestrator lifetime
• Rate limit detection (primary, secondary, credits buckets)

Structured Logging

• Every log line tagged with issue_id, session_id
• Session metrics: turn count, token usage, runtime seconds
• No API tokens ever logged

Web Dashboard (Phoenix LiveView)

# Enable with --port flag
./bin/symphony WORKFLOW.md --port 4000

# Endpoints
GET  /              # LiveView dashboard
GET  /api/v1/state  # JSON summary
GET  /api/v1/<id>   # Issue detail
POST /api/v1/refresh # Force poll now

Status Dashboard (Terminal)

When no port is specified, a terminal-based dashboard renders at 60fps showing running agents, retry queues, token totals, and credit limits.

Configuration

worker:
  ssh_hosts:
    - worker-1.internal
    - worker-2.internal
    - worker-3.internal
  max_concurrent_agents_per_host: 4

How It Works

• Codex app-server launched via SSH on the remote host
• JSON-RPC messages tunneled over the SSH connection's stdio
• Workspaces created remotely via shell scripts
• Orchestrator selects least-loaded host for new dispatches

Load Balancing

Remote Safety

• Shell escaping prevents injection in path variables
• Remote path validation: checks for empty paths and control chars
• Workspace removal is idempotent across hosts
• E2E tests use Docker containers simulating SSH workers

Built-in Protections

• Workspace path validation prevents directory traversal
• Canonical path resolution blocks symlink escapes
• API tokens never exposed to agents
• Environment variable indirection for secrets
• Hooks are fully trusted (come from WORKFLOW.md)
• Agents cannot access other agents' workspaces

Approval Policies

Recommended Hardening

OS user isolation per agent, tighter filesystem permissions, network restrictions, per-workspace approval policies.

BEAM VM Strengths

• Process supervision — OTP supervisors automatically restart crashed processes
• Lightweight concurrency — thousands of processes with minimal overhead
• Fault isolation — one agent crashing cannot bring down the orchestrator
• Hot code reloading — update agent logic without stopping running agents
• Built-in distribution — natural path to multi-node orchestration

OTP Patterns Used

Not Included

• No rich web UI or multi-tenant control plane
• No prescribed approval/sandbox policies (implementation choice)
• No built-in tracker write APIs (agents use tools to update Linear)
• No general-purpose workflow/job scheduler features
• No persistent database or durable state storage
• No built-in CI/CD integration (agents handle that)

Design Philosophy

Symphony focuses on doing one thing well: turning issue tracker tickets into isolated, autonomous agent sessions. Everything else is either delegated to the agent or left to the implementation.

The spec encourages ports in Python, Go, TypeScript, and other languages. The Elixir implementation is a reference, not the only option.

Feedback Loops

• Codex → Linear: Agent uses linear_graphql tool to update issue state, post comments
• Orchestrator → Linear: Reconciliation checks for external state changes every tick
• Codex → Orchestrator: Token usage, rate limits, turn completions reported via events

Concurrency Model

• Global limit: max_concurrent_agents (default 10)
• Per-state limit: max_concurrent_agents_by_state
• Per-host limit: max_concurrent_agents_per_host
• One agent per issue (enforced by claim state)