symphony

symphony-go

Set up, configure, run, and troubleshoot symphony-go — a Go service that turns Linear issues into autonomous Codex coding sessions.

What symphony-go does

Symphony polls a Linear project board, picks up issues in active states (Todo, In Progress), creates isolated workspace directories, and launches Codex app-server agents to work on each issue. When an agent finishes, it opens a PR. Symphony handles retries, backoff, concurrency limits, and workspace cleanup.

Prerequisites

Before setting up symphony-go, make sure these are installed:

1. Codex CLI — npm install -g @openai/codex (verify: codex --version)
2. Linear API key — create at https://linear.app/settings/api, export as LINEAR_API_KEY
3. Linear project — create a project in Linear, note the project slug (short ID in the project URL)
4. Go 1.25+ — only if building from source; pre-built binaries at https://github.com/kwanpham2195/symphony-go/releases

Setup

Step 1: Install symphony-go

# Option A: go install
go install github.com/kwanpham2195/symphony-go/cmd/symphony@latest

# Option B: download binary
# https://github.com/kwanpham2195/symphony-go/releases

# Option C: build from source
git clone https://github.com/kwanpham2195/symphony-go.git
cd symphony-go && make build

Step 2: Create WORKFLOW.md

Create a WORKFLOW.md file in the target repository. This file has two parts:

• YAML front matter — runtime configuration (tracker, workspace, hooks, codex settings)
• Body — a Liquid template rendered as the agent prompt for each issue

Minimal example:

---
tracker:
  kind: linear
  project_slug: "your-project-slug"
  api_key: $LINEAR_API_KEY
workspace:
  root: ~/code/my-workspaces
hooks:
  after_create: |
    git clone --depth 1 https://github.com/your-org/your-repo .
codex:
  command: codex app-server
  approval_policy: never
---

You are working on Linear ticket {{ issue.identifier }}: {{ issue.title }}.

{{ issue.description }}