Skip to main content

​
Symphony

Symphony connects open source projects with AI-powered contributors. Browse curated issues, contribute with one click, and donate your AI compute to projects you care about.

​
Overview

Symphony is Maestro’s open source contribution platform. Projects register with Symphony and create issues tagged with runmaestro.ai. Contributors browse these issues, select one, and Maestro handles the rest: cloning the repository, creating a branch, running the Auto Run documents, and submitting a draft PR. For Contributors: Find meaningful open source work that’s perfectly scoped for AI assistance. For Maintainers: Get AI-powered contributions without writing complex prompts yourself.

​
Getting Started

​
Opening Symphony

Access Symphony from the main menu or use the keyboard shortcut:
  • Menu: Click the hamburger menu and select “Symphony”
  • Keyboard: Press Cmd+Shift+Y (macOS) or Ctrl+Shift+Y (Windows/Linux)

​
Browsing Projects

The Symphony modal displays registered open source projects as tiles. Each tile shows:
  • Project name and description
  • Category (AI/ML, Developer Tools, Infrastructure, etc.)
  • Number of available issues
  • Featured badge (if applicable)
Use the search bar to filter projects by name, or select a category to narrow results.

​
Starting a Contribution

  1. Select a project - Click a project tile to view its available issues
  2. Choose an issue - Browse issues and click one to see details
  3. Review documents - Each issue lists Auto Run documents that define the work
  4. Click “Start Symphony” - Opens the agent creation dialog
  5. Configure the session:
    • Select your AI provider (Claude Code, Codex, OpenCode)
    • Customize the working directory if needed
    • Optionally expand “Advanced” to configure agent options
  6. Click “Create Agent” - Maestro will:
    • Clone the repository to your working directory
    • Create a feature branch (symphony/issue-{number}-{timestamp})
    • Set up the Auto Run documents
    • Start processing the first document

​
During the Contribution

Once started, your contribution appears in the “Active” tab:
  • Progress tracking: See which document is being processed
  • Token usage: Monitor AI compute consumption
  • Time spent: Track how long the contribution has been running
The AI agent will work through each Auto Run document sequentially. You can monitor progress in the main terminal view.

​
Draft PR Creation

Symphony uses a deferred PR strategy:
  1. On start: Branch is created but no PR exists yet
  2. On first commit: A draft PR is automatically created, linking to the issue
  3. Why deferred?: This prevents “empty PR” errors and only claims the issue once real work begins
The draft PR includes:
  • Title: [WIP] Symphony: {Issue Title} (#{issue})
  • Body linking to the original issue
  • “Closes #” to auto-close when merged

​
Automatic Completion

When all Auto Run documents are processed successfully, Symphony automatically:
  1. Marks the PR as ready for review - Converts the draft PR to “Ready for Review”
  2. Posts a contribution summary - Adds a comment with:
    • Token usage (input/output/total)
    • Estimated cost of AI compute donated
    • Time spent processing
    • Documents processed and tasks completed
  3. Credits you - The comment links to Maestro and Symphony
You’ll see a toast notification when completion finishes. If Auto Run is stopped manually, the PR remains in draft state for you to review before finalizing.

​
Contribution Workflow

┌─────────────────┐
│  Browse Issues  │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Start Symphony  │──► Clone repo, create branch
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   Auto Run      │──► Process documents sequentially
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  First Commit   │──► Draft PR created (claims issue)
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  All Documents  │──► Auto-finalize PR + post stats
│    Complete     │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Maintainer      │
│ Review & Merge  │
└─────────────────┘

​
Your Stats

Symphony tracks your contribution statistics:
  • Total contributions: Number of PRs submitted
  • Repositories helped: Unique projects you’ve contributed to
  • Documents processed: Total Auto Run documents completed
  • Estimated cost donated: AI compute value contributed
  • Contribution streak: Consecutive days with contributions
View your stats in the Symphony modal’s stats panel.

​
Tips for Contributors

​
Choosing Issues

  • Start with smaller issues (1-2 documents) to learn the workflow
  • Look for issues with clear, well-documented objectives
  • Check the document previews before starting

​
During Contributions

  • Monitor the AI’s progress in the terminal
  • If the agent gets stuck, you can provide guidance
  • Use the pause button if you need to step away

​
After Completion

  • Review the generated code before finalizing
  • Make manual adjustments if needed
  • Add a comment to the PR explaining any deviations

​
For Maintainers

Want to register your project with Symphony? See:

​
Troubleshooting

​
”GitHub CLI not authenticated”

Symphony requires the GitHub CLI (gh) to be installed and authenticated: 
# Install gh (macOS)
brew install gh

# Authenticate
gh auth login

​
“No commits between branches” error

This error occurred in older versions. Symphony now defers PR creation until the first commit is made, which resolves this issue. Make sure you’re on the latest version.

​
Contribution stuck on “running”

If Auto Run appears stuck:
  1. Check the terminal for any prompts or errors
  2. The AI may be waiting for user input
  3. Try providing guidance or pressing Enter

​
Clone failed

Ensure you have:
  • Internet connectivity
  • Sufficient disk space
  • Git installed and configured