Symphony GitHub

Symphony GitHub is a tmux-based GitHub issue runner for coding agents. It watches one or more GitHub repositories, starts agent work in isolated git worktrees, pushes branches, opens PRs, and can optionally merge them automatically.

It is the GitHub-native successor to dmux: same multi-agent / tmux workflow, but with issue polling, PR automation, progress comments, startup recovery, and swarm orchestration.

What It Does

• watches GitHub issues and comments using configurable trigger rules
• runs Claude, Codex, OpenCode, Gemini, Cline, Qwen, Amp, Pi, Cursor, Copilot, or Crush in isolated worktrees
• opens a tmux TUI showing active runs, review-needed runs, and completed runs
• pushes branches and creates PRs automatically
• supports three run modes:
  • auto: auto-resolve conflicts when possible and auto-merge
  • auto_manual_conflicts: auto-merge unless GitHub reports conflicts
  • auto_manual_merge: stop once the PR is ready for human review/merge
• keeps swarm/autoevolve separate from run mode; enable it with swarm.enabled
• mirrors progress back to GitHub issue / PR comments if enabled
• recovers claimed issues on startup and lets you resume or skip them
• optionally runs a swarm Director that creates follow-up issues, manages blockers, and tracks dependencies

Install

npm install -g symphony-github

Contributor and release notes live in CONTRIBUTING.md.

Or run from a local checkout:

npm install
npm run build
npm start

Prerequisites

• Node.js 18+
• tmux
• git
• gh authenticated against GitHub
• at least one supported agent CLI installed

Sanity checks:

gh auth status
tmux -V
codex --version

Start

Inside a local checkout of the repo you want to work on:

symphony configure
symphony

Useful variants:

# Re-run onboarding against the current config
symphony configure

# Start or reuse the tmux session without attaching immediately
symphony --no-attach

# Use an explicit config path
symphony --config ./config.yaml

If you start detached, Symphony prints the tmux session name and attach command.

TUI

The current TUI has three main areas:

• header: watched repo(s), run mode, counts for running / review / done, and last poll time
• table: issue number, title, status, agent, diff stats, last update time, and an activity sparkline
• preview pane: live tmux output for the selected run, or the startup-recovery / action-menu view

Special states:

• startup recovery view: appears when Symphony finds previously claimed issues on boot
• action menu: opened from the selected run to pause, kill, or label-and-kill it

Keyboard Shortcuts

Normal mode:

• ↑ / ↓: move selection
• Enter: jump to the selected tmux pane
• a: same as Enter
• d: open the action menu for the selected run
• r: resume a run in awaiting_review or needs_attention
• f: finalize a run in awaiting_review
• x: close the selected pane from the local list
• c: reopen onboarding / reconfigure the current project config
• q: quit Symphony
• Ctrl-b 0: return to the Symphony control pane after jumping into an agent pane

Action menu:

• ↑ / ↓: choose action
• Enter: confirm
• Esc: cancel

Startup recovery:

• ↑ / ↓: move selection
• Space: toggle one issue
• a: select all
• n: select none
• Enter: resume selected issues
• s: skip all pending recovery items
• q: quit

Run Modes

Symphony currently supports three run modes:

mode: auto                  # auto-resolve conflicts when possible and merge automatically
mode: auto_manual_conflicts # stop only when conflict resolution needs a human
mode: auto_manual_merge     # stop when the PR is ready for manual merge

Legacy automerge normalizes to auto.

These are the only valid values for mode. Swarm/autoevolve is not a fourth run mode; it is a separate optional orchestration layer configured under swarm.

Swarm Mode

If you want the Director agent / agent-swarm behavior, enable swarm in the YAML config. This can create follow-up issues, pause blocked work, resume unblocked work, and keep evolving the backlog while the normal run mode still controls how worker PRs are merged.

mode: auto

swarm:
  enabled: true
  director:
    agent: claude
    scope: session
    analyze_interval_min: 30
    max_proposed_issues: 5
  proposals:
    approval_mode: auto

Proposal approval behavior:

• auto: automatically approve proposals and create the follow-up issues
• director_review: workers can propose issues, but the Director must approve them first
• human_approval: workers can propose issues, but a human must approve them

symphony configure currently asks only for the three run modes above. Swarm is configured manually in the generated YAML for now.

Configuration

The easiest path is still symphony configure, but the generated YAML is straightforward.

Minimal example:

version: 1

default_agent: codex
mode: auto_manual_merge

github_comments:
  verbosity: key_updates

poll_interval_sec: 2
max_concurrent_runs: 4

agents:
  codex:
    provider: codex
    timeout_min: 30
    create_pr: ready
    push: true

routing:
  mention_map:
    "@agent": codex
    "@codex": codex

repos:
  - owner/repo

trigger:
  mode: label_only
  labels:
    - agent
  mentions:
    - "@agent"
    - "@codex"
  claim_label: agent:running
  done_label: agent:done
  failed_label: agent:failed
  include_existing_open_issues: true

See config.example.yaml for the full schema, including swarm settings.

Try It

Two public repos are meant for trying Symphony quickly:

• mireklzicar/symphony-fixture-todo: deterministic canonical harness
• mireklzicar/symphony-demo-snake: more visual showcase demo

TODO App

Use this when you want the cleanest reproducible demo.

git clone https://github.com/<you>/symphony-fixture-todo.git
cd symphony-fixture-todo
npm install

Seed the canonical conflict demo:

./scripts/create_issues.sh \
  --fixture conflicts \
  --group readme-demo-conflict \
  --label agent

Then start Symphony in that checkout:

symphony configure
symphony

Recommended config choices for this demo:

• agent: codex or claude
• run mode: auto
• trigger mode: label_only
• startup scan: enabled
• GitHub comments: key_updates or silent

Expected result:

• two conflicting README issues are picked up
• Symphony opens and merges two PRs
• the final README sentence ends with the second issue's requested exact text

Snake App

Use this when you want a more fun public demo backlog.

git clone https://github.com/<you>/symphony-demo-snake.git
cd symphony-demo-snake
npm install

Seed the curated demo issues:

./scripts/create_issues.sh --label agent

Then run Symphony in the same repo:

symphony configure
symphony

The snake repo includes demo issues for:

• food spawn correctness
• pause / resume controls
• WASD controls
• responsive layout
• localStorage high score
• extracting gameplay constants into a config module

How Runs Work

1. Symphony polls the configured GitHub repos.
2. It evaluates trigger rules against new / updated issues and comments.
3. Matching issues are claimed with a running label.
4. A dedicated git worktree is created for the run.
5. The selected agent launches in its own tmux pane with issue context.
6. On completion, Symphony inspects the worktree, pushes the branch, and creates or finds the PR.
7. Depending on run mode, Symphony either merges automatically or leaves the run in review.
8. Final labels, comments, and runtime manifests are updated.

Runtime Layout

By default Symphony stores state under ~/.symphony/:

~/.symphony/
  cache/
  repos/
  runs/
  state.json
  swarm/
  version.json
  worktrees/

Important per-run files:

~/.symphony/runs/
  r_<timestamp>-owner__repo-issue-random/
    manifest.json
    events.jsonl

Agent Environment

Before each run, Symphony exports:

• SYMPHONY_REPO
• SYMPHONY_ISSUE_NUMBER
• SYMPHONY_ISSUE_URL
• SYMPHONY_WORKTREE
• SYMPHONY_BRANCH
• SYMPHONY_CONTEXT_FILE
• SYMPHONY_RUN_ID
• SYMPHONY_RUN_DIR
• SYMPHONY_AGENT
• SYMPHONY_AGENT_PROVIDER

It also writes .symphony/issue.json and .symphony/context.md into the worktree.

License

MIT