symphony-trackers

Symphony

Symphony watches your issue tracker and autonomously works tickets end-to-end using Claude. Each ticket gets an isolated workspace, a fresh clone of the target repository, and a Claude agent that implements, tests, opens a PR, and moves the ticket through your workflow — unattended.

How it works

1. Symphony polls your tracker (Jira or Linear) for tickets in configured active states.
2. For each eligible ticket it creates an isolated workspace directory.
3. It clones the target repository into that workspace (hooks.after_create).
4. It launches a Claude agent with the ticket context as the prompt.
5. The agent works until the ticket reaches a terminal state or the turn limit is hit.
6. When done, Symphony cleans up the workspace.

One Symphony process handles one workflow file (one tracker project + one repository). Run multiple processes in parallel to cover multiple repos.

---

Prerequisites

Elixir runtime

Install mise to manage Elixir/Erlang versions:

brew install mise

Then inside this repo:

cd elixir
mise trust
mise install

Claude CLI

Install and authenticate Claude Code:

npm install -g @anthropic-ai/claude-code
claude login

GitHub CLI

Required for the agent to open PRs and interact with GitHub:

brew install gh
gh auth login

---

Install

Clone and build the Symphony binary:

git clone https://github.com/wagnersza/symphony
cd symphony/elixir
mise exec -- mix setup
mise exec -- mix build

This produces elixir/bin/symphony.

---

Tracker setup

Jira

Create a .env file at the root of this repo (it is gitignored):

JIRA_API_TOKEN=your-jira-api-token
[email protected]
JIRA_SITE_URL=https://your-org.atlassian.net
JIRA_PROJECT_KEY=YOUR_PROJECT_KEY

Getting a Jira API token:

1. Go to Atlassian API tokens
2. Click Create API token, give it a name (e.g. symphony), and copy the value

Board statuses Symphony expects by default:

Status	Role
To Do	Queued — agent picks up and moves to In Progress
In Progress	Agent is actively working
Doing	Treated the same as In Progress
UNDER REVIEW	PR submitted — waiting for human review
Done	Terminal — not touched
Backlog	Terminal — not touched

You can override active_states and terminal_states in your workflow file to match your board.

Linear

Add to your .env file:

LINEAR_API_KEY=lin_api_xxxxxxxxxxxxxxxxxxxx
LINEAR_PROJECT_SLUG=your-project-slug

Getting a Linear API key:

1. Go to Settings → API → Personal API keys
2. Click Create key, give it a name (e.g. symphony), and copy the value

Finding your project slug:

Open a Linear issue URL — it looks like https://linear.app/your-org/issue/PROJ-123. The slug is the segment after your org name (e.g. your-org). You can also use the team identifier shown on your Linear workspace settings.

Default Linear states Symphony uses:

Status	Role
Todo	Queued
In Progress	Agent is actively working
Done	Terminal
Cancelled / Canceled	Terminal

---

Workflow files

A workflow file is a Markdown file with a YAML front matter block that configures the tracker, workspace, agent limits, and hooks — followed by a Jinja2 prompt template that is sent to the agent for each ticket.

Available template variables: {{ issue.identifier }}, {{ issue.title }}, {{ issue.state }}, {{ issue.description }}, {{ issue.labels }}, {{ issue.url }}, {{ attempt }}.

Jira example

---
tracker:
  kind: jira
  jira:
    site_url: "$JIRA_SITE_URL"
    email: "$JIRA_EMAIL"
    api_token: "$JIRA_API_TOKEN"
    project_key: "$JIRA_PROJECT_KEY"
  active_states:
    - To Do
    - In Progress
  terminal_states:
    - Done
    - Backlog
polling:
  interval_ms: 30000
workspace:
  root: ~/code/symphony-workspaces/myrepo
hooks:
  after_create: |
    git clone --depth 1 https://github.com/your-org/your-repo .
    npm install
agent:
  max_concurrent_agents: 3
  max_turns: 20
codex:
  command: claude -p --dangerously-skip-permissions
  approval_policy: never
  thread_sandbox: workspace-write
  turn_sandbox_policy:
    type: workspaceWrite
---

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

...

See elixir/WORKFLOW.jira.example.md for a complete Jira starter template.

Linear example