symphony-skills

Symphony Elixir

This directory contains the current Elixir/OTP implementation of Symphony, based on SPEC.md at the repository root.

[!WARNING] Symphony Elixir is prototype software intended for evaluation only and is presented as-is. We recommend implementing your own hardened version based on SPEC.md.

Screenshot

How it works

1. Polls Linear for candidate work
2. Creates a workspace per issue
3. Launches Codex in App Server mode inside the workspace
4. Sends a workflow prompt to Codex
5. Refreshes new external Linear comments between turns for active sessions
6. Keeps Codex working on the issue until the work is done

During app-server sessions, Symphony serves client-side Linear tools:

• linear_graphql for raw GraphQL access
• linear_create_comment for supported issue replies
• linear_update_comment for supported workpad/comment edits

Continuation turns prepend a compact New Linear comments since last turn section when Symphony detects fresh external comments while the issue remains active.

If a claimed issue moves to a terminal state (Done, Closed, Cancelled, or Duplicate), Symphony stops the active agent for that issue and cleans up matching workspaces.

How to use it

1. Make sure your codebase is set up to work well with agents: see Harness engineering.
2. Get a new personal token in Linear via Settings → Security & access → Personal API keys, and set it as the LINEAR_API_KEY environment variable.
3. Copy this directory's WORKFLOW.md to your repo.
4. Optionally copy the commit, push, pull, land, and linear skills to your repo.
   • The linear skill expects Symphony's linear_graphql app-server tool for raw Linear GraphQL operations such as comment editing or upload flows.
5. Customize the copied WORKFLOW.md file for your project.
   • To get your project's slug, right-click the project and copy its URL. The slug is part of the URL.
   • When creating a workflow based on this repo, note that it depends on non-standard Linear issue statuses: "Rework", "Human Review", and "Merging". You can customize them in Team Settings → Workflow in Linear.
6. Follow the instructions below to install the required runtime dependencies and start the service.

Deploy with Docker

Option A: Install Script (recommended for fresh servers)

One command to set up everything on Ubuntu 22.04/24.04:

curl -fsSL https://raw.githubusercontent.com/markoinla/symphony/main/install.sh | sudo bash

This installs Docker, Node.js, Claude Code CLI, and GitHub CLI, then starts Symphony with Postgres. Workflow files are installed to ~/.symphony/workflows/ where you can edit them — changes are picked up automatically.

After install:

1. Open http://<your-server-ip>:4000/setup and create your admin account (email + password)
2. Settings → Connect Linear OAuth
3. Projects → Create a project (name, GitHub repo, Linear org/project slug)

To add more users:

docker exec symphony-app-1 mix symphony.create_user [email protected] secretpassword --name "Full Name"

Workflows

Default workflow files are installed to ~/.symphony/workflows/:

~/.symphony/workflows/
├── WORKFLOW.md
├── ENRICHMENT.md
├── EPIC_SPLITTER.md
├── MENTION.md
├── REVIEW.md
└── TRIAGE.md

Edit these files to customize agent behavior — Symphony hot-reloads changes automatically. To add a new workflow, drop any .md file with valid YAML front matter into the directory.

Management commands

Update — pulls latest images and restarts services:

sudo bash /opt/symphony/install.sh --update

Reset authentication — removes all user accounts so you can re-run /setup:

sudo bash /opt/symphony/install.sh --reset-password

Uninstall — stops all services and removes data:

sudo bash /opt/symphony/install.sh --uninstall

View logs:

cd /opt/symphony && docker compose -f docker-compose.prod.yml logs -f

Option B: Manual Docker Compose

Prerequisites

On your server, install and authenticate:

• Docker and Docker Compose
• Claude CLI — installed and logged in (claude auth login)
• GitHub CLI — installed and logged in (gh auth login)

Quick start

git clone https://github.com/markoinla/symphony.git
cd symphony
echo "HOST_HOME=$HOME" > .env
docker compose up -d

Open http://localhost:4000:

1. Visit /setup to create your admin account (email + password)
2. Settings → Connect Linear OAuth
3. Projects → Create a project (name, GitHub repo, Linear org/project slug)
4. Create an issue in Linear — Symphony picks it up

To update: docker compose pull && docker compose up -d

Option C: Deploy with Dokploy