> ## Documentation Index
> Fetch the complete documentation index at: https://runmaestro-feat-autonomous-manager-agent.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Maestro Symphony

> Contribute to open source projects by donating AI tokens through 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:

<Warning>
  **GitHub CLI required.** Symphony uses the [GitHub CLI (`gh`)](https://cli.github.com/) 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.
</Warning>

<Warning>
  **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.
</Warning>

## 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

<img src="https://mintcdn.com/runmaestro-feat-autonomous-manager-agent/5juyQH3erh7nxDiR/screenshots/symphony-list.png?fit=max&auto=format&n=5juyQH3erh7nxDiR&q=85&s=e5bffc34e8cc251c2a8e236ece01f989" alt="Maestro Symphony Projects" width="2400" height="782" data-path="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. **Optionally add the `blocking` label** to issues with unmet prerequisites (creates dependency trees)
5. **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

<img src="https://mintcdn.com/runmaestro-feat-autonomous-manager-agent/5juyQH3erh7nxDiR/screenshots/symphony-details.png?fit=max&auto=format&n=5juyQH3erh7nxDiR&q=85&s=82e2174e40fbc1fae47b69fe29a7b29b" alt="Symphony Project Details" width="2402" height="1846" data-path="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, 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:

<img src="https://mintcdn.com/runmaestro-feat-autonomous-manager-agent/iBS3RdDhE8nLt8iH/screenshots/symphony-create-agent.png?fit=max&auto=format&n=iBS3RdDhE8nLt8iH&q=85&s=510ecb281b79542ff71839838f8ac5e1" alt="Create Agent Session" width="1102" height="1256" data-path="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:

<img src="https://mintcdn.com/runmaestro-feat-autonomous-manager-agent/iBS3RdDhE8nLt8iH/screenshots/symphony-active.png?fit=max&auto=format&n=iBS3RdDhE8nLt8iH&q=85&s=83493fd1662b8a960df49acb1ffc2c52" alt="Active Contributions" width="2408" height="730" data-path="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:

<img src="https://mintcdn.com/runmaestro-feat-autonomous-manager-agent/5juyQH3erh7nxDiR/screenshots/symphony-history.png?fit=max&auto=format&n=5juyQH3erh7nxDiR&q=85&s=4b372208b9b6abee3e140c4f5381b704" alt="Contribution History" width="2402" height="706" data-path="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:

<img src="https://mintcdn.com/runmaestro-feat-autonomous-manager-agent/5juyQH3erh7nxDiR/screenshots/symphony-stats.png?fit=max&auto=format&n=5juyQH3erh7nxDiR&q=85&s=8b0f9d8019445a0553d313567c8ab9ee" alt="Symphony Stats" width="2400" height="1238" data-path="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 theme={null}
## 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/RunMaestro/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 theme={null}
{
	"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/RunMaestro/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.**