--- 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: View all issues labeled `runmaestro.ai` — ready for AI-assisted contribution --- **Maestro Symphony — Advancing open source, together.**