diff --git a/.claude/skills/release-notes/SKILL.md b/.claude/skills/release-notes/SKILL.md new file mode 100644 index 0000000000..e313db398e --- /dev/null +++ b/.claude/skills/release-notes/SKILL.md @@ -0,0 +1,336 @@ +--- +name: release-notes +description: > + Generate polished release notes and update the README for PolyPilot releases. + Use when: (1) A new version tag has been pushed and needs release notes, + (2) The user asks to prepare release notes for a version, + (3) The README needs updating with new features or a "What's New" section, + (4) Preparing a release announcement or changelog entry. + Covers: commit categorization, highlight extraction, README update strategy, + GitHub Release body formatting, and the release workflow integration. +--- + +# Release Notes & README Update Skill + +## Overview + +PolyPilot releases follow semantic versioning (`v1.0.x`) with tags pushed to `main`. +The GitHub Actions workflow (`.github/workflows/build.yml`) creates releases via +`softprops/action-gh-release@v1` with `generate_release_notes: false` โ€” meaning +the release body must be explicitly provided or updated after creation. + +Currently, release notes default to GitHub's auto-generated "What's Changed" PR list, +which is noisy and hard to scan. This skill produces **curated, highlight-driven +release notes** and keeps the README current. + +--- + +## Step 1: Gather Changes Since Last Release + +**Start with commits, then ALWAYS read PR bodies for the headline features.** +The commit subject line is never enough โ€” the PR body has the "why", the architecture +decisions, and the user-facing description you need for highlights. + +```bash +# Find the previous tag +PREV_TAG=$(git tag --sort=-v:refname | head -2 | tail -1) +CURR_TAG=$(git tag --sort=-v:refname | head -1) + +# List commits between tags (overview) +git --no-pager log ${PREV_TAG}..${CURR_TAG} --oneline + +# CRITICAL: Read PR bodies for any feat: commits โ€” this is where the good stuff is +gh pr view --json body -q '.body' + +# Batch: get all merged PRs with titles and bodies +gh pr list --state merged --search "merged:>=$(git log -1 --format=%ci $PREV_TAG | cut -d' ' -f1)" --limit 50 --json number,title,labels,body +``` + +If preparing notes for a release that hasn't been tagged yet, compare against `HEAD`: +```bash +git --no-pager log ${PREV_TAG}..HEAD --oneline +``` + +**Do not skip reading PR bodies.** A commit that says `feat: mixed-model PR Review Squad` +tells you nothing. The PR body explains that 5 Opus workers each dispatch 3 sub-agents +across Opus/Sonnet/Codex and synthesize 2-of-3 consensus reports. That's the highlight. + +--- + +## Step 2: Categorize Changes + +Group commits by type using conventional commit prefixes and PR content: + +### Categories (in display order) + +| Emoji | Category | Commit Prefixes | Description | +|-------|----------|----------------|-------------| +| ๐Ÿš€ | **Highlights** | (manually curated) | Top 1-3 most impactful changes โ€” the "headline" | +| โœจ | **New Features** | `feat:` | New capabilities, commands, UI elements | +| ๐Ÿ› | **Bug Fixes** | `fix:` | Corrections to existing behavior | +| โšก | **Performance** | `perf:`, `fix:` (perf-related) | Speed, memory, render improvements | +| ๐Ÿ“ฑ | **Mobile** | any mobile/bridge-related | Remote mode, bridge, mobile UI | +| ๐Ÿค– | **Multi-Agent** | orchestrat*, squad, worker | Orchestration, presets, squad teams | +| ๐Ÿ”ง | **Infrastructure** | `chore:`, `ci:`, `build:` | CI/CD, deps, tooling | +| ๐Ÿ“ | **Documentation** | `docs:` | README, docs/, skill updates | + +### Rules for Highlights + +Highlights are the **most user-visible, exciting changes**. Pick 1-3 from the full list. +Good highlights: +- New features users will immediately notice (new UI, new command, new integration) +- Major reliability improvements that fix frequent pain points +- New platform support or significant UX redesign + +Bad highlights: +- Internal refactors (even big ones) +- Test fixes +- CI/CD changes +- Minor bug fixes + +### Writing Style + +- **Active voice, present tense**: "Adds Fiesta mode for multi-machine orchestration" +- **User-focused**: Describe what users can do, not what code changed +- **Concise**: One line per item, 10-15 words max +- **Include PR numbers**: `(#123)` at end for traceability +- **Group related PRs**: If 3 PRs fix mobile streaming, combine into one line + +--- + +## Step 3: Write the Release Notes + +### Template + +```markdown +## ๐Ÿš€ Highlights + +- **[Headline feature]** โ€” one-sentence description of the most exciting change (#PR) +- **[Second highlight]** โ€” another major improvement (#PR) + +## โœจ New Features + +- Feature description in active voice (#PR) +- Another feature (#PR) + +## ๐Ÿ› Bug Fixes + +- Fix description โ€” what was broken and what works now (#PR) +- Another fix (#PR) + +## โšก Performance + +- What got faster and by how much (#PR) + +## ๐Ÿ”ง Infrastructure + +- CI/CD, build, or tooling change (#PR) + +--- + +**Full Changelog**: https://github.com/PureWeen/PolyPilot/compare/vPREV...vCURR + +**Install / Update:** +- **macOS:** `brew upgrade polypilot` โ€” or download [PolyPilot.zip](https://github.com/PureWeen/PolyPilot/releases/download/vCURR/PolyPilot.zip) +- **Windows:** [PolyPilot-Windows.zip](https://github.com/PureWeen/PolyPilot/releases/download/vCURR/PolyPilot-Windows.zip) +- **Android:** [PolyPilot-Android.apk](https://github.com/PureWeen/PolyPilot/releases/download/vCURR/PolyPilot-Android.apk) +- **Linux:** [.deb](https://github.com/PureWeen/PolyPilot/releases/download/vCURR/polypilot_CURR_amd64.deb) ยท [.AppImage](https://github.com/PureWeen/PolyPilot/releases/download/vCURR/PolyPilot-CURR-x86_64.AppImage) ยท [.flatpak](https://github.com/PureWeen/PolyPilot/releases/download/vCURR/com.microsoft.PolyPilot.flatpak) +``` + +Replace `vCURR`/`vPREV` with actual tag names (e.g., `v1.0.17`) and `CURR` with the +bare version (e.g., `1.0.17`). The asset filenames match what `.github/workflows/build.yml` +uploads (lines 719-727). Actual assets per release: `PolyPilot.zip` (macOS), +`PolyPilot-Windows.zip`, `PolyPilot-Android.apk`, `polypilot_{ver}_amd64.deb`, +`PolyPilot-{ver}-x86_64.AppImage`, `com.microsoft.PolyPilot.flatpak`. + +### Example (real v1.0.15 notes, rewritten) + +```markdown +## ๐Ÿš€ Highlights + +- **Fiesta Mode** โ€” Discover and orchestrate across multiple PolyPilot instances on your LAN with push-to-pair (#322) +- **Mixed-Model PR Review Squad** โ€” New preset combining Opus, Sonnet, and Codex for comprehensive code review (#451) + +## โœจ New Features + +- Surface CLI subagent and skill events directly in chat + `/agent` command (#445) +- Add sync button for mobile with diagnostic logging (#438) +- Surface auth errors with actionable guidance messages (#446) + +## ๐Ÿ› Bug Fixes + +- Fix mobile streaming: bypass render throttle, debounce broadcasts, fix stale IsProcessing (#447, #449) +- Fix cleared input fields re-filling with stale draft text on re-render (#435) +- Fix orchestrator over-dispatching workers for single-task prompts (#429) +- Forward full system environment to CLI child process (#439) +- Recover restored session model and expose gpt-5.4 (#448) +- Use `.git/info/exclude` instead of `.gitignore` for worktree exclusions (#434) +- Never abort sessions on resume โ€” removes RESUME-ABORT behavior (#452) + +## ๐Ÿ”ง Infrastructure + +- Fix structural tests to find call sites instead of method definitions (#453) +- Fix flaky ProcessHelper test catching leaked exceptions (#454) + +--- + +**Full Changelog**: https://github.com/PureWeen/PolyPilot/compare/v1.0.14...v1.0.15 +``` + +--- + +## Step 4: Publish the Release Notes + +### Option A: Update an existing GitHub Release + +```bash +# Update the release body for an existing tag +gh release edit v1.0.16 --notes-file /tmp/release-notes.md +``` + +### Option B: Create a new release (if not auto-created by CI) + +```bash +gh release create v1.0.17 \ + --title "v1.0.17" \ + --notes-file /tmp/release-notes.md \ + --draft +``` + +### Workflow + +1. Write the notes to a temp file (never commit temp files) +2. Use `gh release edit` to update the existing release +3. Verify: `gh release view v1.0.16` + +--- + +## Step 5: Update the README + +### Philosophy: The README Sells, It Doesn't Document + +The README is a **landing page**, not a technical spec. It should make someone excited +to try PolyPilot in 30 seconds of scrolling. Every sentence should answer "what can I do?" +not "how is it implemented?" + +**Good README voice:** +- "Launch pre-built agent teams with one click โ€” 5 workers dispatch sub-agents across models and synthesize consensus reviews" +- "Scan a QR code, control your agent fleet from your pocket" +- "Set a goal and let the agent loop: execute โ†’ evaluate โ†’ refine โ†’ repeat" + +**Bad README voice (too implementation-focused):** +- "Uses ConcurrentDictionary for thread-safe session management" +- "Events from the SDK arrive on background threads and are marshaled via SynchronizationContext.Post" +- "The 3-tier timeout system handles quiescent sessions (30s), active tool execution (10min), and general inactivity (2min)" + +### What to Update (and when) + +| Trigger | README Section | Action | +|---------|---------------|--------| +| New major feature | Key Features | Add or update a feature block | +| Feature significantly reworked | Key Features | Rewrite the block with new capabilities | +| New platform supported | Supported Platforms | Update the table | +| New install method | Getting Started | Add install instructions | +| New slash command | Slash Commands | Add to the list | +| Test count milestone | Testing | Update the number | + +### Structure + +The README follows this flow (preserve it): + +``` +1. Logo + badges + tagline +2. Screenshot +3. "What is PolyPilot?" โ€” one paragraph + quick-scan table +4. "Key Features" โ€” the showcase (biggest section, most visual) +5. "Supported Platforms" โ€” table with install links +6. "Getting Started" โ€” Homebrew + build from source +7. "Self-Building Workflow" โ€” the meta story +8. "Testing" โ€” brief +9. Footer +``` + +### Adding a New Feature to Key Features + +Follow this pattern โ€” short heading, 1-3 sentences max, focus on what the user gets: + +```markdown +### ๐ŸŽ‰ Feature Name +What it lets you do in one sentence. Maybe a second sentence with a concrete example +or the "wow" detail. Never mention implementation classes or internal architecture. +``` + +Consolidate related capabilities. Don't add a separate section for every PR โ€” group +"CLI Agent Visibility" and "/agent command" into one "Any Model, Any Task" section +rather than three separate entries. + +### What NOT to Put in the README + +- Version-specific changelog (goes in GitHub Releases) +- "What's New in v1.0.x" sections (gets stale instantly) +- Internal architecture (ConcurrentDictionary, SynchronizationContext, event marshaling) +- Timeout values, watchdog tiers, or other implementation constants +- Dates or timestamps + +--- + +## Step 6: Verify + +After updating: + +```bash +# Verify release notes look right +gh release view $CURR_TAG + +# Verify README renders correctly (check for broken markdown) +# Look for: unclosed code blocks, broken links, missing images +cat README.md | head -5 # should start with

+ +# Ensure no temp files are left +git status --short +``` + +--- + +## Automation Integration + +The release workflow in `.github/workflows/build.yml` (line ~717) uses: +```yaml +- name: Create Release + uses: softprops/action-gh-release@v1 + with: + generate_release_notes: false + draft: false +``` + +To integrate automated release notes, the workflow could be updated to: +1. Add a step before `Create Release` that generates the notes body +2. Pass the body to the `softprops/action-gh-release` action via the `body` or `body_path` input +3. This could use a script that calls `gh api` to get merged PRs and formats them + +However, the **recommended approach** is to run this skill manually before or after +tagging a release. Curated notes are always better than fully automated ones. + +--- + +## Quick Reference Commands + +```bash +# List recent tags +git tag --sort=-v:refname | head -5 + +# Commits since last tag +git --no-pager log $(git tag --sort=-v:refname | head -1)..HEAD --oneline + +# Merged PRs since a date +gh pr list --state merged --search "merged:>=2026-03-25" --limit 30 + +# Update release notes +gh release edit v1.0.16 --notes-file /tmp/release-notes.md + +# View current release notes +gh release view v1.0.16 + +# README preview (if you have grip installed) +# grip README.md +``` diff --git a/README.md b/README.md index bf1338a9cc..ce62e38e7b 100644 --- a/README.md +++ b/README.md @@ -9,201 +9,144 @@

- Multi-agent orchestration โ€ข Real-time streaming โ€ข Cross-platform โ€ข Remote access from your phone + Latest Release + Downloads + Platforms

--- -## What is PolyPilot? - -PolyPilot is a **multi-agent control plane for GitHub Copilot**. It's a cross-platform native app (macOS, Windows, Android, iOS) built with .NET MAUI and Blazor that lets you spin up, orchestrate, and monitor **dozens of parallel Copilot coding agents** โ€” each with its own model, working directory, and conversation โ€” all from one dashboard. - -Think of it as **mission control for AI-powered development**: you launch agents, assign them tasks across different repos, watch them work in real time, and manage everything from a single pane of glass โ€” or from your phone while you're away from your desk. +

+ PolyPilot Dashboard +

-### Why PolyPilot? +## What is PolyPilot? -The Copilot CLI is powerful, but it's one agent in one terminal. What if you could: +**Mission control for AI-powered development.** Launch dozens of GitHub Copilot agents, assign them to different repos, watch them work in real time, and manage everything from one dashboard โ€” or from your phone. -- ๐Ÿš€ **Run 10+ Copilot agents simultaneously**, each working on a different task or repo -- ๐Ÿ”„ **Resume any session** across app restarts โ€” your agents never lose context -- ๐Ÿ“ฑ **Monitor and control everything from your phone** via secure WebSocket bridge and DevTunnel -- ๐Ÿง  **Mix and match models** โ€” Claude, GPT, Gemini โ€” in the same workspace -- ๐Ÿ—๏ธ **Organize agents into groups**, pin favorites, and sort by activity -- ๐ŸŒฟ **Manage repos and worktrees** โ€” clone repos, create branches, spin up isolated worktrees per agent +| | | +|---|---| +| ๐Ÿš€ **Run 10+ agents simultaneously** | Each with its own model, repo, and conversation | +| ๐Ÿง  **Mix models freely** | Claude Opus + GPT-5 + Sonnet in the same workspace | +| ๐Ÿค– **One-click team presets** | PR Review Squad, multi-agent orchestration, custom squads | +| ๐Ÿ“ฑ **Control from your phone** | Scan a QR code, manage your fleet from anywhere | +| ๐ŸŽ‰ **Fiesta Mode** | Spread work across multiple machines on your LAN | +| ๐Ÿ”„ **Sessions never die** | Persistent across restarts, auto-reconnect, auto-resume | -That's PolyPilot. +--- ## โœจ Key Features -### ๐ŸŽ›๏ธ Multi-Session Orchestrator Dashboard -A real-time grid view of all active agents. Each card shows streaming output, tool execution status, token usage, and queue depth. Send targeted prompts to individual agents from a single dashboard. +### ๐ŸŽ›๏ธ Fleet Dashboard +A real-time grid of all active agents. Streaming output, tool execution, token usage โ€” everything at a glance. Send prompts to any agent without switching windows. -### ๐Ÿ’ฌ Rich Chat Interface -Full-featured chat UI with streaming responses, Markdown rendering (code blocks, inline code, bold), real-time activity indicators, and auto-scrolling. See exactly what each agent is thinking and doing โ€” including tool calls, reasoning blocks, and intent changes. +

+ PolyPilot Chat +

-### ๐Ÿ”ง Live Agent Activity Feed -Watch your agents work in real time: `๐Ÿ’ญ Thinking...` โ†’ `๐Ÿ”ง Running bash...` โ†’ `โœ… Tool completed`. Full visibility into multi-step agentic workflows with tool execution tracking and reasoning transparency. +### ๐Ÿค– Multi-Agent Teams +Launch pre-built or custom agent teams with one click: -### ๐Ÿ’พ Session Persistence & Resume -Sessions survive app restarts. Active sessions are automatically saved and restored. Conversation history is reconstructed from event logs. Browse and resume any previously saved session from the sidebar โ€” agents never lose their place. +- **PR Review Squad** โ€” 5 Opus workers each dispatch 3 sub-agents (Opus, Sonnet, Codex) and synthesize consensus reviews +- **Custom Squads** โ€” Drop a `.squad/` directory in your repo with agent charters, routing rules, and shared context +- **Worktree Strategies** โ€” Shared, orchestrator-isolated, or fully-isolated branches per agent -### ๐Ÿ“ฑ Remote Access from Your Phone -Run agents on your desktop, monitor from your phone. PolyPilot's WebSocket bridge + Azure DevTunnel integration creates a secure tunnel so you can watch agents work, send prompts, and manage sessions from anywhere. Just scan a QR code to connect. +### ๐ŸŽ‰ Fiesta Mode +Turn your LAN into a compute cluster. Discover other PolyPilot instances, pair with a string or push-to-pair, then dispatch tasks to any machine with `@worker-name`. One PolyPilot to rule them all. -### ๐Ÿง  Multi-Model Support -Create sessions with different AI models and compare results side by side. Assign Claude to one task, GPT to another, and Gemini to a third โ€” all running in parallel in the same workspace. +### ๐Ÿ“ฑ Remote Access +Your agents run on your desktop. You control them from your pocket. -### ๐Ÿ“‚ Per-Session Working Directories -Point each agent at a different repo or directory. Native folder pickers on macOS and Windows. Manage worktrees for parallel git operations across agents. +1. Start a tunnel in Settings (powered by [Azure DevTunnels](https://learn.microsoft.com/en-us/azure/developer/dev-tunnels/)) +2. Scan the QR code on your phone +3. Full control: send prompts, watch streaming output, manage sessions -### ๐ŸŒฟ Repository & Worktree Management -Clone repositories, create branches and worktrees, and launch sessions โ€” all from the sidebar. **Quick Branch + Session** creates a new branch and session in one click. **Named Branch + Session** lets you specify a branch name or PR number (`#123`). Worktrees are tracked, linked to sessions, and cleaned up automatically when sessions close. +### ๐Ÿ’ฌ Rich Chat +Streaming Markdown, code blocks, reasoning traces, tool call visualization, and real-time activity indicators (`๐Ÿ’ญ Thinking...` โ†’ `๐Ÿ”ง Running bash...` โ†’ `โœ… Done`). You see everything the agent sees. -### ๐Ÿค– Multi-Agent Presets & Squad Teams -Launch pre-configured teams with one click. Built-in presets like **PR Review Squad** spin up an orchestrator plus multiple workers, each with their own model and role. Auto-discovers `.squad` and `.ai-team` directories in your repos for custom team definitions with agent charters and routing configs. +### ๐Ÿง  Any Model, Any Task +Create sessions with different models and compare results side by side. Claude for architecture, GPT for code generation, Gemini for review โ€” all in parallel. Models are assigned per-session, and the `/agent` command lets you select specialized CLI agents (code-review, security-review) on the fly. -### ๐Ÿ”€ Worktree Strategies -Control how multi-agent teams share code: -- **Shared** โ€” all agents work in the same directory -- **Orchestrator Isolated** โ€” orchestrator gets its own branch, workers share one -- **Fully Isolated** โ€” every agent gets a unique worktree and branch for zero-conflict parallel work +### ๐ŸŒฟ Git-Native Workflow +- **Quick Branch + Session** โ€” one click to create a branch and start coding +- **Named Branch + Session** โ€” specify a name or PR number (`#123`) +- **Worktree management** โ€” clone, branch, isolate โ€” all from the sidebar +- **Auto-cleanup** โ€” worktrees are tracked and removed when sessions close -### ๐Ÿ—๏ธ Session Organization -Groups, pinning, and multiple sort modes (Last Active, Created, Aโ€“Z, Manual) let you manage large fleets of agents without losing track. Collapsible groups keep things tidy. +### ๐Ÿ” Reflection Cycles +Set a goal and let the agent loop: execute โ†’ evaluate โ†’ refine โ†’ repeat. Configurable iteration limits and completion criteria. Perfect for TDD and multi-step tasks. -### ๐ŸŽ‰ Fiesta Mode โ€” Multi-Machine Orchestration -Discover and link other PolyPilot instances on your LAN. Start a "Fiesta" to fan out work to linked worker machines via `@mention` routing. Workers are discovered automatically and linked in Settings. Use `@worker-name` in your prompts to dispatch tasks to specific machines. +### ๐Ÿ’พ Bulletproof Persistence +Sessions survive everything โ€” app restarts, machine reboots, CLI crashes. History is reconstructed from event logs. A 3-tier watchdog recovers stuck agents automatically. No zombie sessions, no lost work. ### โŒจ๏ธ Slash Commands -Built-in slash commands give you quick control without leaving the chat: `/help`, `/clear`, `/version`, `/compact`, `/new`, `/sessions`, `/rename`, `/diff`, `/status`, `/mcp`, `/plugin`. - -### ๐Ÿ”” Smart Notifications -Get notified when agents finish tasks, encounter errors, or need your attention โ€” even when the app is in the background. +Quick control without leaving the chat: `/help` `/clear` `/compact` `/new` `/sessions` `/rename` `/diff` `/status` `/mcp` `/plugin` `/agent` -### ๐Ÿ›ก๏ธ Processing Watchdog -Automatically detects agents stuck in a "Thinking..." state and recovers them. A 3-tier timeout system handles quiescent sessions (30s), active tool execution (10min), and general inactivity (2min) โ€” no more zombie sessions. - -### ๐Ÿ” Reflection Cycles -Goal-based iterative refinement for agents. Set a goal, and the agent will loop โ€” executing, evaluating, and refining โ€” until it meets the completion criteria or hits a max iteration count. Great for test-driven workflows and multi-step tasks. - -### ๐Ÿ“Š Usage Stats -Track session metrics: messages sent, tokens used, session duration, and lines suggested. Visible in the bottom bar for quick reference. +### ๐Ÿ”” Notifications & Tailscale +Get notified when agents finish or hit errors โ€” even in the background. Tailscale VPN is detected automatically for easy fleet sharing across your network. ### ๐ŸŽฎ Demo Mode -Test the UI without a Copilot connection. The built-in demo service simulates streaming responses, tool calls, and activity indicators with realistic timing. - -### ๐Ÿ”Œ Flexible Connection Modes -From embedded stdio for quick single-machine use, to a persistent server that survives app restarts, to remote mode for mobile access โ€” pick the transport that fits your workflow. - -### ๐Ÿ›ก๏ธ Auto-Reconnect -If an agent's underlying process dies mid-conversation, PolyPilot automatically resumes the session and retries โ€” transparent to you. - -### ๐Ÿ”„ Git Auto-Update -When running from a git checkout, PolyPilot can automatically detect and pull updates from the main branch โ€” keeping your instance up to date without manual intervention. - -### ๐ŸŒ Tailscale Integration -Detects your Tailscale VPN status and IP automatically, making it easy to share your agent fleet across your Tailscale network. - -## ๐Ÿ” Iterating on PolyPilot โ€” Self-Building Workflow - -PolyPilot is designed to be developed **from within itself**. You can open a Copilot session pointed at the PolyPilot repo, make changes, and use the included `relaunch.sh` script to seamlessly rebuild and relaunch โ€” all without leaving the app. - -### How it works +Try the full UI without a Copilot connection โ€” simulated streaming, tool calls, and activity indicators with realistic timing. -```bash -# macOS -./relaunch.sh - -# Windows -powershell -ExecutionPolicy Bypass -File relaunch.ps1 -``` - -On macOS, the script: -1. **Builds** the project (`dotnet build -f net10.0-maccatalyst`) -2. **Copies** the built app to a staging directory -3. **Launches** the new instance -4. **Verifies** the new instance is stable (waits a few seconds) -5. **Kills** the old instance โ€” seamless handoff, no downtime - -On Windows, `relaunch.ps1` follows the same pattern for the WinUI target. - -If the build fails, the old instance keeps running and you see clear error output. No stale binaries are ever launched. - -This means an agent working inside PolyPilot can edit code, run `./relaunch.sh`, and immediately test its own changes in the freshly-built app โ€” a tight feedback loop for AI-driven development. - -> **Most of PolyPilot's features were built by GitHub Copilot coding agents โ€” orchestrated from within PolyPilot itself.** +--- -## Supported Platforms +## ๐Ÿ–ฅ๏ธ Supported Platforms -| Platform | Status | -|----------|--------| -| **macOS** (Mac Catalyst) | โœ… Primary development target | -| **Windows** | โœ… Supported | -| **Android** | โœ… Supported (Remote mode) | -| **iOS** | โœ… Supported (Remote mode) | -| **Linux** (GTK head) | ๐Ÿงช Experimental (`PolyPilot.Gtk`) | +| Platform | Status | Install | +|----------|--------|---------| +| **macOS** | โœ… Primary | `brew install --cask polypilot` | +| **Windows** | โœ… Supported | [Download .zip](https://github.com/PureWeen/PolyPilot/releases/latest) | +| **Android** | โœ… Supported | [Download .apk](https://github.com/PureWeen/PolyPilot/releases/latest) | +| **iOS** | โœ… Supported | [Build from source](https://github.com/PureWeen/PolyPilot#build-from-source) | +| **Linux** | ๐Ÿงช Experimental | [.deb / .AppImage / .flatpak](https://github.com/PureWeen/PolyPilot/releases/latest) | -Mobile devices connect to a desktop instance via WebSocket bridge โ€” run your agent fleet on your workstation, control it from your pocket. +Mobile connects to a desktop instance via WebSocket bridge โ€” your fleet runs on the workstation, your phone is the remote control. -## Getting Started +## ๐Ÿš€ Getting Started -### Install with Homebrew (macOS) +### Homebrew (macOS โ€” recommended) ```bash brew tap PureWeen/tap brew install --cask polypilot ``` -This installs the notarized PolyPilot.app and the GitHub Copilot CLI automatically. - -### Prerequisites (build from source) - -- **.NET 10 SDK** (Preview) -- **.NET MAUI workload** โ€” `dotnet workload install maui` -- **GitHub Copilot CLI** โ€” `brew install copilot-cli` or `npm install -g @github/copilot` -- **GitHub Copilot subscription** +### Build from Source -### Build & Run +**Prerequisites:** [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0) + `dotnet workload install maui` + [GitHub Copilot CLI](https://docs.github.com/en/copilot) + Copilot subscription ```bash cd PolyPilot # macOS -dotnet build -f net10.0-maccatalyst -open bin/Debug/net10.0-maccatalyst/maccatalyst-arm64/PolyPilot.app - -# Or use the hot-relaunch script for iterative development -./relaunch.sh +./relaunch.sh # Build + hot-relaunch # Windows dotnet build -f net10.0-windows10.0.19041.0 -# Android (deploy to connected device) +# Android dotnet build -f net10.0-android -t:Install -# Linux (GTK head) -dotnet build PolyPilot.Gtk/PolyPilot.Gtk.csproj +# Linux dotnet run --project PolyPilot.Gtk/PolyPilot.Gtk.csproj ``` -## ๐Ÿงช Testing - -PolyPilot has two layers of testing: +## ๐Ÿ” Self-Building Workflow -- **1,200+ unit tests** (xUnit, .NET 10) โ€” deterministic tests covering models, services, multi-agent orchestration, persistence, and parsing. Run with `cd PolyPilot.Tests && dotnet test`. -- **Executable UI scenarios** (JSON + MauiDevFlow CDP) โ€” end-to-end flows validated against a running app instance. 25+ multi-agent scenarios (reflection loops, Squad discovery, group lifecycle) and 10+ mode-switch scenarios. +PolyPilot builds itself. Open a Copilot session pointed at the PolyPilot repo, make changes, run `./relaunch.sh`, and the app seamlessly rebuilds and relaunches โ€” no downtime, no stale binaries, no leaving the app. -The test project shares source files with the main MAUI project via `` links, so tests run on any machine without platform SDKs. `ScenarioReferenceTests.cs` cross-references every CDP scenario with its deterministic unit-test equivalent. +> **Most of PolyPilot's features were built by GitHub Copilot coding agents โ€” orchestrated from within PolyPilot itself.** -See [`docs/testing.md`](docs/testing.md) for the full testing guide, scenario format, and how to add new tests. +## ๐Ÿงช Testing -## ๐Ÿ“ฑ Remote Access via DevTunnel +- **3,000+ unit tests** โ€” models, services, orchestration, persistence, parsing +- **Executable UI scenarios** โ€” end-to-end CDP flows validated against a running instance -Mobile devices connect to your desktop over [Azure DevTunnels](https://learn.microsoft.com/en-us/azure/developer/dev-tunnels/) โ€” a secure tunnel to control your agent fleet from anywhere. +```bash +cd PolyPilot.Tests && dotnet test +``` -1. Install the DevTunnel CLI (`brew install --cask devtunnel` on macOS, `winget install Microsoft.devtunnel` on Windows) -2. In PolyPilot Settings, click **Login with GitHub** then **Start Tunnel** -3. Scan the **QR code** from your phone to connect instantly +See [`docs/testing.md`](docs/testing.md) for the full guide. ---