Symphony orchestration

Symphony moves the team from supervising coding agents to managing work. You scope a ticket and drop it into a queue state; Symphony runs Codex in a clean per-issue sandbox, Claude reviews the PR, and the work comes back to you as a pull request ready for a merge decision. The practical interface is Linear — state transitions start, gate, and stop every run.

Hold five roles in mind. Linear decides what, Symphony decides when, Codex does the work, Claude checks it, GitHub delivers it.

The system splits into three layers — a control plane humans touch, the Symphony service daemon, and per-issue execution. Each has its own design below; the slate seam node in every diagram is the handoff to the adjacent layer. Click any node to trace its connections.

The states are Symphony-prefixed so normal team work is never picked up by accident. The work ping-pongs between you and the machine — colour marks who moves each state. Only four are watched (polled as active); the rest are handoff gates or terminal. Play the happy path, or click any state to inspect it.

The happy path for a single issue, from claim to complete. Each normal turn ends with a re-check of the Linear state; while the issue stays active, the worker continues on the same Codex thread up to max_turns.

Mandatory after the PR exists and before every transition to Symphony Human Review. The loop is automatic: opening a PR or pushing a commit triggers a fresh Claude review, so the last fix commit is always reviewed without a manual ping.

Validation is progressive — a repo:* label selects which checks render, so the smallest relevant gate runs instead of every check on every ticket. If labels are missing, Codex infers the target repo from the title, description, stack trace, and changed files, then reads that repo's AGENTS.md. Pick a repo.

Beyond ticket execution, systemd timers run a second cadence: housekeeping that keeps the VPS healthy, and report-only QA routes that create their own Linear issues for Symphony to pick up. This is the self-improving half — a fast loop does the work, a slow loop watches how the work is going.

The dashboard is private to the VPS. Reach it over an SSH tunnel; the same data is on a JSON state API. A runtime snapshot reports running and retrying sessions, per-session turn counts, aggregate Codex token totals, runtime seconds, and the latest rate-limit payload.

# tunnel the private dashboard to localhost
ssh -L 4000:127.0.0.1:4000 symphony@138.201.190.183
# then open http://127.0.0.1:4000/

curl -fsS http://127.0.0.1:4000/api/v1/state | jq
curl -fsS http://127.0.0.1:4000/api/v1/ENG-123 | jq
curl -X POST http://127.0.0.1:4000/api/v1/refresh

The service runs as the unprivileged symphony user. Do not edit /opt/symphony directly — change code locally, push, then git pull --ff-only on the VPS. Treat any VPS or service change as operational work: capture the command, evidence, and a rollback note.

# service health + logs
ssh root@138.201.190.183 'systemctl is-active symphony'
ssh root@138.201.190.183 'journalctl -u symphony -f'
ssh root@138.201.190.183 'systemctl restart symphony'

The highest operational risk is handing agents too many ambiguous tickets at once. Broaden deliberately.

• Start at max_concurrent_agents: 1. One test ticket at a time.
• After several clean issues, raise the cap to 2; add per-state limits if merge or rework should be stricter than implementation.
• Keep the Symphony-prefixed Linear states until the team trusts the workflow.
• Add SSH workers only when the single VPS is CPU, memory, or disk constrained.
• Broaden eligible states only after the issue template and review culture are reliable.

• OpenAI: an open-source spec for Codex orchestration — Symphony
• Symphony service specification (SPEC.md)
• Symphony Elixir reference implementation
• Harness engineering (OpenAI)
• Compound engineering (Every)