Symphony

1. 1

   Poll

   Query Linear on a fixed cadence (default 5s) for candidate issues in active states.

2. 2

   Claim

   Lock an eligible issue (concurrency-bounded) to prevent duplicate dispatch across restarts.

3. 3

   Create Workspace

   Provision at <workspace.root>/<issue-id> and run the after_create hook (typically git clone).

4. 4

   Build Prompt

   Render the WORKFLOW.md template with issue variables ({{ issue.title }}, {{ issue.description }}, etc.).

5. 5

   Launch Codex

   Start Codex in app-server mode inside the workspace and stream turns back.

6. 6

   Keep Working

   After each normal turn, re-check issue state. If still active, run another turn on the same thread — up to agent.max_turns.

7. 7

   Reconcile

   If the issue moves to a terminal state (Done / Closed / Cancelled / Duplicate), stop the agent and clean up.

8. 8

   Blocked Handling

   If Codex needs operator input / approval / secrets, Symphony keeps the issue claimed and surfaces it as blocked (in-memory only).

Claim States

Within Claimed: sub-states include Running and RetryQueued.

Run-Attempt Lifecycle

---
tracker:
  kind: linear
  project_slug: "your-project"
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
---

You are working on Linear issue {{ issue.identifier }}.
Title: {{ issue.title }}
Body: {{ issue.description }}

Key Config Fields

# Prereqs: mise, Linear account, Codex CLI
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

Wire Up Linear + Your Repo

1. 1

   Confirm Agent-Friendliness

   Make sure your codebase is set up for harness engineering — tests, CI, clear boundaries.

2. 2

   Create Linear API Key

   Settings → Security & access → export LINEAR_API_KEY.

3. 3

   Copy & Configure WORKFLOW.md

   Set project_slug + after_create clone command. Optionally copy the commit / push / pull / land skills.

4. 4

   Add Custom Linear Statuses

   Add Rework, Human Review, Merging in Team Settings → Workflow — or edit the workflow to match your board.

Runtime Flags

• ./bin/symphony /path/to/custom/WORKFLOW.md — custom workflow (defaults to ./WORKFLOW.md)
• --logs-root <dir> — log directory (default ./log)
• --port <n> — enables the optional Phoenix dashboard + JSON API

Without the dashboard, structured logs cover token accounting and humanized event summaries — documented in elixir/docs/.

• Autonomy is real. The reference codex.command uses approval_policy: never + workspace-write. That's deliberate for trusted setups — treat it as a loaded tool.
• Workspace safety is a hard invariant. The agent's turn cwd must never be the source repo; everything stays under workspace.root. The Elixir impl enforces this in path_safety.ex.
• Restart = amnesia for scheduler state. Blocked issues and in-flight retry timers are in memory only. After a restart, still-active issues become dispatch candidates again.
• GitHub is not a valid blocker in the shipped workflow — the agent must exhaust fallback auth/remotes before flagging blocked.
• Terminal cleanup on startup removes stale workspaces for issues already done — expect disk churn.
• SSH workers are an optional extension (Appendix A): run agents on remote hosts over SSH; the e2e test can spin up disposable Docker SSH workers.

Quick Reference

• Spec: SPEC.md — domain model §4, workflow contract §5, config §6, state machine §7, scheduling §8, workspace safety §9, agent protocol §10, Linear integration §11, reference algorithms §16, checklist §18
• Reference impl: elixir/ — orchestrator.ex, agent_runner.ex, workspace.ex, config.ex, linear/, codex/
• Workflow: elixir/WORKFLOW.md
• Skills: .codex/skills/{commit, push, pull, land, linear, debug}
• Test gate: make all · live e2e: make e2e
• Demo: Vimeo