Maestro Symphony

Maestro Symphony is a community-driven program that connects Maestro users with open source repository maintainers seeking contributions. Think of it like distributed computing for AI-assisted development — instead of donating CPU cycles, users donate LLM tokens to advance open source.

Prerequisites

Before starting a Symphony contribution, ensure you have:

GitHub CLI required. Symphony uses the GitHub CLI (gh) to create draft PRs, manage contributions, and claim issues. Install it and run gh auth login to authenticate. Symphony will verify this before allowing you to proceed.

Build tools required. Symphony clones repositories and runs Auto Run documents that may compile code, run tests, and make changes. Make sure you have the project’s build tools and dependencies installed (e.g., Node.js, Python, Rust toolchain). Consider cloning the project first and verifying you can build it successfully — without the right toolchain, the contribution will likely fail.

How It Works

For Contributors

Browse available projects directly within Maestro
Select a GitHub issue that matches your interests
Create a dedicated agent session — choose your AI provider and model
Single-click contribution — Maestro clones the repo, runs Auto Run docs, and creates a PR

For Repository Owners

Define contribution opportunities as Auto Run documents in your repository
Open a GitHub issue listing the document paths
Add the runmaestro.ai label to make it visible to the Maestro community
Optionally add the blocking label to issues with unmet prerequisites (creates dependency trees)
Receive quality pull requests generated by AI-assisted workflows

Opening Symphony

Method	Description
`Cmd+Shift+Y` / `Ctrl+Shift+Y`	Keyboard shortcut
Quick Actions → “Maestro Symphony”	Command palette (`Cmd+K`)
Hamburger Menu → “Maestro Symphony”	Menu item

Browsing Projects

The Symphony modal has four tabs: Projects, Active, History, and Stats.

Projects Tab

The Projects tab shows registered open source projects in a tiled grid:

Category filters — Filter by AI/ML, Developer Tools, etc.
Search — Find projects by name, description, or tags
Project tiles — Click to view available issues
Keyboard navigation — Use arrow keys to navigate, Enter to select, / to focus search

Select a repository to see its available GitHub issues. Each issue shows:

Issue title and number
Number of Auto Run documents to process
Document previews with a dropdown selector (use Cmd+Shift+[ / Cmd+Shift+] to cycle documents)
Status indicator (available, in-progress with PR link, or blocked)

Blocked Issues

Issues with the blocking label appear in a separate “Blocked” section, grayed out with a lock icon. These represent work that has unmet prerequisites — the repository maintainer will remove the blocking label once dependencies are satisfied. Blocked issues cannot be started but are shown so contributors can see the full scope of planned work.

Starting a Contribution

Click Start Symphony on an available issue to open the agent creation dialog:

Configure your contribution:

AI Provider — Choose Claude Code, Codex, OpenCode, etc.
Session Name — Pre-filled as “Symphony: owner/repo #123”
Working Directory — Where the repository will be cloned

Click Create Agent and Maestro will:

Clone the repository to ~/Maestro-Symphony/{owner}-{repo}/ (default location, customizable)
Create a new branch (symphony/{issue-number}-{short-id})
Set up Auto Run documents (external attachments downloaded to cache, repo docs referenced in place)
Begin processing tasks automatically
Create a draft PR on first commit (claims the issue so others know it’s in progress)

Tracking Contributions

Active Tab

View your in-progress Symphony sessions:

Each active contribution shows:

Issue title and repository — The GitHub issue being worked on
Status badge — Running, Paused, Creating PR, etc.
Progress bar — Documents completed vs. total
Current document — The document being processed
Time elapsed — How long the contribution has been running
Token usage — Input/output tokens and estimated cost
Draft PR link — Once created on first commit
Controls — Pause/Resume, Cancel, Finalize PR

Click Check PR Status to verify your draft PR on GitHub and detect merged/closed PRs.

History Tab

Review completed contributions with aggregate stats at a glance:

The header shows your totals: PRs created, merged count, tasks completed, tokens used, and dollar value donated. Each contribution card displays:

Issue and repository — What you worked on
Merge status — Whether the PR was merged
Completion date — When you finished
PR link — Direct link to the pull request
Detailed metrics — Documents processed, tasks completed, tokens used, and cost

Stats Tab

Track your overall impact and unlock achievements:

Summary cards show your cumulative contributions:

Tokens Donated — Total tokens contributed with dollar value
Time Contributed — Hours spent and repositories helped
Streak — Current and best contribution streaks

Achievements reward milestones in your Symphony journey:

Achievement	Requirement
First Steps	Complete your first Symphony contribution
Merged Melody	Have a contribution merged
Weekly Rhythm	Maintain a 7-day contribution streak
Harmony Seeker	Complete 10 contributions
Ensemble Player	Contribute to 5 different repositories
Virtuoso	Complete 1000 tasks across all contributions
Token Millionaire	Donate over 10 million tokens
Early Adopter	Join Symphony in its first month

Session Integration

Symphony sessions appear in the Left Bar like any other session:

Named “Symphony: owner/repo #123”
Optionally grouped under a “Symphony” group
Full access to AI Terminal, Command Terminal, and Auto Run controls

You can interact with Symphony sessions just like regular sessions — pause Auto Run, make manual edits, or switch to the Command Terminal for custom commands.

Creating Symphony-Ready Issues

Repository owners create issues with the runmaestro.ai label:

## Add unit tests for auth module

We need comprehensive test coverage for the authentication module.

### Auto Run Documents

- `docs/symphony/auth-tests-1.md`
- `docs/symphony/auth-tests-2.md`
- `docs/symphony/auth-tests-3.md`

### Context

The auth module is at `src/auth/index.ts`. Tests should use Jest.

Each document path should point to an Auto Run-compatible markdown file with task checkboxes.

Task Claiming

Symphony uses deferred PR creation to avoid GitHub’s “no commits between branches” error. When you start a contribution, Maestro sets up the branch and documents but waits until the first commit to create the draft PR:

Start contribution → Branch created locally, Auto Run begins processing
First commit → Draft PR automatically created, claims the issue
Subsequent commits → Push to the same PR

This means issues show as “in progress” once the first commit lands. The claiming mechanism:

No draft PR → Task is available
Draft PR exists → Task is in progress (first to commit wins)

Registering Your Project

To add your open source project to Symphony:

Fork the Maestro repository
Add your project to symphony-registry.json in the root directory
Submit a pull request to the main Maestro repository

Your project entry should include:

{
	"slug": "owner/repo",
	"name": "Project Name",
	"description": "Brief description",
	"url": "https://github.com/owner/repo",
	"category": "ai-ml",
	"tags": ["tag1", "tag2"],
	"maintainer": {
		"name": "Your Name",
		"url": "https://github.com/yourusername"
	},
	"isActive": true,
	"featured": false,
	"addedAt": "2025-01-01"
}

Available Categories

Category	Label	Emoji
`ai-ml`	AI & ML	🤖
`developer-tools`	Developer Tools	🛠️
`infrastructure`	Infrastructure	🏗️
`documentation`	Documentation	📚
`web`	Web	🌐
`mobile`	Mobile	📱
`data`	Data	📊
`security`	Security	🔒
`other`	Other	📦

Once merged, your project will appear in the Symphony Projects tab (registry cached for 2 hours, issues cached for 5 minutes).

Available Issues

Browse Symphony-ready issues on Maestro itself: