---
title: Maestro Symphony
description: Contribute to open source projects by donating AI tokens through Maestro Symphony.
icon: music
---

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.

## How It Works

### For Contributors

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

![Maestro Symphony Projects](./screenshots/symphony-list.png)

### For Repository Owners

1. **Define contribution opportunities** as Auto Run documents in your repository
2. **Open a GitHub issue** listing the document paths
3. **Add the `runmaestro.ai` label** to make it visible to the Maestro community
4. **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

![Symphony Project Details](./screenshots/symphony-details.png)

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 or in-progress with PR link)

## Starting a Contribution

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

![Create Agent Session](./screenshots/symphony-create-agent.png)

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:

1. Clone the repository to `~/Maestro-Symphony/{owner}-{repo}/` (default location, customizable)
2. Create a new branch (`symphony/{issue-number}-{short-id}`)
3. Set up Auto Run documents (external attachments downloaded to cache, repo docs referenced in place)
4. Begin processing tasks automatically
5. 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:

![Active Contributions](./screenshots/symphony-active.png)

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:

![Contribution History](./screenshots/symphony-history.png)

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:

![Symphony Stats](./screenshots/symphony-stats.png)

**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:

```markdown
## 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:

1. **Start contribution** → Branch created locally, Auto Run begins processing
2. **First commit** → Draft PR automatically created, claims the issue
3. **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:

1. Fork the [Maestro repository](https://github.com/pedramamini/Maestro)
2. Add your project to `symphony-registry.json` in the root directory
3. Submit a pull request to the main Maestro repository

Your project entry should include:
```json
{
  "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:

<Card title="Maestro Symphony Issues" icon="github" href="https://github.com/pedramamini/Maestro/issues?q=is%3Aissue%20label%3Arunmaestro.ai">
  View all issues labeled `runmaestro.ai` — ready for AI-assisted contribution
</Card>

---

**Maestro Symphony — Advancing open source, together.**
