If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/XcodesOrg/XcodesApp shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 8mo ago
• 13 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 8mo ago
• ⚠ Concentrated ownership — top contributor handles 69% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live XcodesOrg/XcodesApp repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/XcodesOrg/XcodesApp.

What it runs against: a local clone of XcodesOrg/XcodesApp — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in XcodesOrg/XcodesApp | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 262 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of XcodesOrg/XcodesApp. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/XcodesOrg/XcodesApp.git
#   cd XcodesApp
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of XcodesOrg/XcodesApp and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "XcodesOrg/XcodesApp(\\.git)?\\b" \\
  && ok "origin remote is XcodesOrg/XcodesApp" \\
  || miss "origin remote is not XcodesOrg/XcodesApp (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "Xcodes/Backend/AppState.swift" \\
  && ok "Xcodes/Backend/AppState.swift" \\
  || miss "missing critical file: Xcodes/Backend/AppState.swift"
test -f "Xcodes/Backend/HelperClient.swift" \\
  && ok "Xcodes/Backend/HelperClient.swift" \\
  || miss "missing critical file: Xcodes/Backend/HelperClient.swift"
test -f "Xcodes/AppleAPI/Sources/AppleAPI/Client.swift" \\
  && ok "Xcodes/AppleAPI/Sources/AppleAPI/Client.swift" \\
  || miss "missing critical file: Xcodes/AppleAPI/Sources/AppleAPI/Client.swift"
test -f "Xcodes/Backend/Downloader.swift" \\
  && ok "Xcodes/Backend/Downloader.swift" \\
  || miss "missing critical file: Xcodes/Backend/Downloader.swift"
test -f "Xcodes/Backend/DataSource.swift" \\
  && ok "Xcodes/Backend/DataSource.swift" \\
  || miss "missing critical file: Xcodes/Backend/DataSource.swift"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 262 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~232d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/XcodesOrg/XcodesApp"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

XcodesApp is a native macOS GUI application that automates the installation and switching of multiple Xcode versions with a single click. It downloads Xcode from Apple's servers using aria2 (up to 16 parallel connections for 3-5x faster downloads), manages installation state, and integrates with xcode-select to switch active versions. The app also supports installing iOS/tvOS/watchOS/visionOS runtimes and Apple Silicon variants. Monolithic Xcode project (Xcodes.xcodeproj/) with a main app target and a privileged XPC helper target (com.robotsandpencils.XcodesApp.Helper). The app uses SwiftUI for the UI layer. Build scripts in Scripts/ handle notarization, version bumping, and packaging. AppCast/ contains a Jekyll-based update mechanism (appcast.xml for Sparkle updates). HelperXPCShared/ contains shared code between the main app and the XPC helper for privilege-escalated operations.

macOS developers who need to work with multiple Xcode versions for compatibility testing, cross-version SDK support, or beta features. DevOps engineers automating CI/CD pipelines that require specific Xcode versions. Contributors to this repo are Swift/macOS app developers interested in system integration and privileged helper processes.

Production-ready and actively maintained. The project is now part of the XcodesOrg GitHub organization (as noted in README), has CI/CD workflows (GitHub Actions in .github/workflows/), notarization scripts (Scripts/notarize.sh), and supports multiple languages with community localization. Recent activity includes beta feature support (iOS 18+, visionOS 2+) and Apple Silicon variant handling.

Low-to-moderate risk: the app requires Apple ID authentication to download Xcode, which adds complexity around credential storage and Apple's API stability. The privileged helper (HelperXPCShared/HelperXPCShared.swift) uses XPC for elevation, which is a sensitive attack surface. No visible test directory in the file list suggests limited automated test coverage. Single-maintainer concern for a tool many developers depend on; however, the XcodesOrg structure may mitigate this.

Active development on runtimes/platforms support (iOS 18+, tvOS 18+, watchOS 11+, visionOS 2+) and Apple Silicon variants (Xcode 26+). Release automation via release-drafter.yml and appcast.yml. Experiments feature flag added for unxip performance optimization (using saagarjha/unxip). Localization ongoing with community contributions (French, Italian, Spanish, Korean, Russian, Turkish, Hindi, Chinese-Simplified, Finnish).

git clone https://github.com/XcodesOrg/XcodesApp.git
cd XcodesApp
open Xcodes.xcodeproj

Then build and run the 'Xcodes' scheme in Xcode. The project uses Swift Package Manager (Package.resolved in .xcshareddata/swiftpm/). No external package manager like CocoaPods; dependencies managed via SPM and Xcode project settings.

Daily commands: Open Xcodes.xcodeproj in Xcode and press Cmd+R to build and run the main target. The privileged helper (com.robotsandpencils.XcodesApp.Helper) is code-signed and installed via XPC. For release builds, use Scripts/package_release.sh.

• Xcodes/Backend/AppState.swift — Core state management for the entire application; orchestrates downloads, installations, and runtime management—every feature depends on this.
• Xcodes/Backend/HelperClient.swift — Bridges the main app to privileged helper operations; handles elevated permission tasks required for Xcode installation.
• Xcodes/AppleAPI/Sources/AppleAPI/Client.swift — Authenticates with Apple Developer servers and fetches available Xcode versions; foundational for discovering installable builds.
• Xcodes/Backend/Downloader.swift — Manages aria2-based multi-connection downloads with resume logic; critical for reliable, fast Xcode acquisition.
• Xcodes/Backend/DataSource.swift — Abstracts data fetching from multiple sources (Apple API, Xcode Releases); enables version discovery and filtering.
• Xcodes.xcodeproj/project.pbxproj — Xcode project configuration; defines build targets, signing identity, and helper tool setup required for macOS app delivery.

Add a new Xcode version discovery source

1. Create a new data source conforming to the discovery protocol in DataSource.swift (Xcodes/Backend/DataSource.swift)
2. Parse the remote response and map to AvailableXcode models (Xcodes/Backend/AvailableXcode.swift)
3. Update AppState to fetch from the new source alongside existing sources (Xcodes/Backend/AppState.swift)

Add a new privileged operation to the helper

1. Define new operation case in the XPC protocol shared by app and helper (HelperXPCShared/HelperXPCShared.swift)
2. Implement handler in the privileged helper (located outside main app bundle) (Xcodes/Backend/HelperClient.swift)
3. Call the new operation from HelperClient and integrate into AppState workflow (Xcodes/Backend/AppState.swift)

Add Apple API authentication or endpoint

1. Add request signing logic or headers in URLRequest+Apple.swift (Xcodes/AppleAPI/Sources/AppleAPI/URLRequest+Apple.swift)
2. Implement new API call in the Client with response decoding (Xcodes/AppleAPI/Sources/AppleAPI/Client.swift)
3. Integrate fetched data into DataSource or AppState for use in UI (Xcodes/Backend/DataSource.swift)

Add a new download or installation step

1. Define the step in the download pipeline (Downloader.swift or Downloads.swift) (Xcodes/Backend/Downloader.swift)
2. Update AppState+Install to call the new step and handle progress/errors (Xcodes/Backend/AppState+Install.swift)
3. Add corresponding UI state updates to track progress (Xcodes/Backend/HelperInstallState.swift)

• SwiftUI + Combine — Native macOS framework for reactive, declarative UI tied to AppState; minimal external dependencies for a system tool.
• aria2 — Multi-connection HTTP downloader (16 connections) provides 3–5x faster downloads than URLSession, critical for large .xip files (12–15 GB).
• XPC / SMJobBless — Privileged helper required for moving files to /Applications and running xcode-select; sandboxed app cannot do this directly.
• Swift Package Manager — Modularizes AppleAPI and AcknowledgementsGenerator; cleaner dependency management and testing of network logic.

• aria2 subprocess over pure-Swift HTTP library

  • Why: aria2 is battle-tested for resumable, parallel downloads; writing equivalent in pure Swift would be complex and unmaintainable.
  • Consequence: External dependency; requires aria2 binary bundled; process lifecycle management overhead.

• XPC helper separate from main app

  • Why: macOS sandbox and code signing require elevated operations in a separate privileged helper.
  • Consequence: Adds architectural complexity (IPC, separate binary, launchd registration) but enables App Store / notarization compliance.

• Apple ID authentication required (no public downloads)

  • Why: Apple only distributes Xcode to authenticated developers via developer.apple.com; no public mirror exists.
  • Consequence: Users must have a valid Apple ID; cannot automate for CI/CD without stored credentials.

• Fallback to Xcode Releases API for discovery

  • Why: Apple API can be rate-limited; Xcode Releases provides reliable version metadata without Apple auth.
  • Consequence: Dual data sources require reconciliation; potential stale data if Xcode Releases lags Apple releases.

• Does not manage Apple ID credentials persistently; relies on system Keychain.
• Does not provide command-line interface (separate xcodes CLI repo exists).
• Does not support Linux or Windows; macOS-only tool.
• Does not automate Xcode updates (users init

Privileged helper: The XPC helper must be installed and code-signed correctly; misalignment between main app bundle ID and helper bundle ID (com.robotsandpencils.XcodesApp.Helper) breaks privilege escalation. Apple ID: App requires valid Apple ID credentials stored securely (likely Keychain); missing or revoked credentials silently fail downloads. Notarization: Release builds must be notarized (notarize.sh); skipping this prevents distribution and breaks Gatekeeper. aria2 dependency: Downloads rely on aria2 subprocess; it must be available in PATH or bundled; missing aria2 falls back to URLSession silently. xcode-select path: System Xcode installation detection via xcode-select is fragile; parallel installations or manual path changes may confuse the app.

• XPC (XPC Services) — XcodesApp uses XPC to communicate with a privileged helper process for system-level operations like xcode-select; understanding this architecture is crucial for adding elevated privilege features
• Code Signing & Notarization (macOS) — Distribution requires Apple notarization (Scripts/notarize.sh) and proper code signing; neglecting this blocks users on modern macOS versions due to Gatekeeper
• Privilege Escalation Pattern (Helper Tools) — XcodesApp separates the unprivileged GUI from a privileged helper; this pattern is fundamental to safely performing system operations like xcode-select without running the entire app as root
• Multi-connection Downloading (aria2) — XcodesApp downloads Xcode via aria2 with 16 parallel connections for 3-5x speed; understanding aria2's resume and segmentation logic is key to optimizing or debugging download failures
• Sparkle Framework & AppCast Feed — XcodesApp auto-updates via Sparkle's RSS/XML-based appcast mechanism; AppCast/ contains the Jekyll-generated feed that drives version discovery and update prompts
• SwiftUI + AppKit Integration (macOS) — XcodesApp mixes SwiftUI for modern UI with AppKit for system integration (menu bar, file dialogs); understanding UIHostingController and NSApplication lifecycle is essential for UI changes
• Resume-capable HTTP Downloads — XcodesApp must resume interrupted Xcode downloads (often 10+ GB); this requires HTTP Range request support, partial file caching, and checksum validation

• XcodesOrg/xcodes — Command-line sibling to XcodesApp; same download/install logic but CLI-driven, used in CI pipelines
• saagarjha/unxip — Fast .xip extraction tool referenced in XcodesApp's experiments feature; used to speed up Xcode installation unarchiving by up to 70%
• sparkle-project/Sparkle — macOS app update framework; XcodesApp uses Sparkle's appcast.xml format for auto-updates (AppCast/ directory)
• aria2/aria2 — Multi-connection download manager; XcodesApp relies on aria2 as subprocess for fast 16-connection Xcode downloads
• apple/swift-package-manager — Dependency manager used in XcodesApp; SPM configuration visible in Xcodes.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add unit tests for AppleAPI Client and authentication flow

The AppleAPI/Sources/AppleAPI/Client.swift handles critical authentication and API communication with Apple's servers. This is a high-risk, core component with no visible test coverage in the file structure. Adding comprehensive unit tests would prevent regressions in authentication, session management, and API error handling—critical for an app that downloads and installs Xcode.

• [ ] Create Xcodes/AppleAPI/Tests directory structure following SPM conventions
• [ ] Add unit tests for Client.swift covering: successful authentication, token refresh, API errors, network failures, and session validation
• [ ] Mock URLSession and Apple API responses to avoid external dependencies in tests
• [ ] Add tests for Environment.swift to verify correct API endpoint configuration
• [ ] Integrate tests into CI pipeline by updating .github/workflows/ci.yml to run SPM tests for AppleAPI package

Add integration tests for download and installation workflows in CI

The repo has Scripts/ directory with critical installation logic (notarize.sh, package_release.sh, sign_update, fix_libfido2_framework.sh) but no visible integration tests validating the end-to-end download/install flow. The current ci.yml workflow appears to only run basic builds. Adding integration tests would catch breaking changes in the installation pipeline before release.

• [ ] Review and document the install workflow steps currently in Scripts/ directory
• [ ] Create a new GitHub Actions workflow (.github/workflows/integration-tests.yml) that runs on pull requests
• [ ] Add integration test steps that: mock downloading a test Xcode version, validate signature verification from appcast, simulate installation, and verify file integrity
• [ ] Use test fixtures in a new Tests/Fixtures/ directory to avoid downloading real Xcode versions during testing
• [ ] Document expected behavior in CONTRIBUTING.md for contributors running integration tests locally

Add automated tests for AcknowledgementsGenerator and document SPM dependency licensing workflow

The AcknowledgementsGenerator tool at Xcodes/AcknowledgementsGenerator/ is responsible for generating licenses for SPM dependencies, but has no test coverage. Additionally, CONTRIBUTING.md doesn't document how contributors should handle new SPM dependencies or run the acknowledgements generator. This creates friction for new contributors and risks incomplete license attribution.

• [ ] Create Xcodes/AcknowledgementsGenerator/Tests/ with unit tests for: parsing Package.resolved, filtering dependencies, and generating valid license output
• [ ] Add test fixtures with sample Package.resolved files covering edge cases (monorepo dependencies, local packages, different Swift versions)
• [ ] Add documentation to CONTRIBUTING.md explaining: when to run AcknowledgementsGenerator, how to test it locally, and requirements for adding new SPM dependencies
• [ ] Update .github/workflows/ci.yml to automatically run AcknowledgementsGenerator on Package.resolved changes and verify output is committed
• [ ] Document the license verification process in DECISIONS.md if licensing decisions exist

• Add automated tests for the download resume logic (aria2 + URLSession fallback); test suite directory is missing, so create Tests/DownloadResumeTests with assertions for partial file recovery
• Improve error messaging for failed Apple ID authentication; currently likely shows generic XPC errors; add specific Keychain error codes and user-friendly strings in Xcodes/Localization
• Document the privileged helper setup process in CONTRIBUTING.md; explain XPC bundle ID matching, codesign requirements, and how to test locally without notarization

• High · Privileged Helper Installation Without Security Hardening Verification — Scripts/uninstall_privileged_helper.sh, Scripts/sign_update, HelperXPCShared/. The presence of 'uninstall_privileged_helper.sh' and 'sign_update' scripts suggests the application uses a privileged helper for elevated operations. Without reviewing the actual implementation, there's a risk that the privileged helper may not properly validate requests, implement proper code signing verification, or use secure IPC mechanisms. Fix: Verify that the XPC privileged helper implements: (1) Strict code signing validation for all callers, (2) Input validation for all IPC messages, (3) Principle of least privilege, (4) Secure entitlements configuration in the Xcode project
• High · Potential Code Signing and Notarization Vulnerabilities — Scripts/notarize.sh, Scripts/package_release.sh, Scripts/sign_update. Scripts for notarization and package release are present but their implementation cannot be verified. Improper notarization or code signing could allow malicious code distribution or bypass of security checks. Fix: Ensure: (1) Notarization properly validates before distribution, (2) Code signing uses hardened runtime entitlements, (3) Timestamping is enabled for all signatures, (4) Review CI/CD pipeline for signing key management
• High · External Download with Potential MITM Risk — Backend/Downloader.swift, AppleAPI/Sources/AppleAPI/Client.swift. The application downloads Xcode versions from external sources (Apple Developer website and xcodereleases.com). The README mentions aria2 for downloading but lacks explicit mention of certificate pinning or checksum verification mechanisms. Fix: Implement: (1) HTTPS with certificate pinning for Apple domains, (2) Cryptographic checksum verification of all downloads, (3) Signature verification using Apple's official public keys, (4) Secure TLS configuration with minimum TLS 1.2
• Medium · Third-Party Dependency Management Without Lock File — AppCast/Gemfile, Xcodes.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/Package.resolved. While Package.resolved exists in the xcshareddata directory, there's a Ruby Gemfile in the AppCast directory without a verified lock file referenced in the structure provided, potentially leading to inconsistent builds. Fix: Ensure all dependencies are locked: (1) Keep Gemfile.lock committed and up-to-date, (2) Regularly audit Swift Package dependencies for vulnerabilities, (3) Use dependency scanning tools in CI/CD
• Medium · Build Script Execution Risks — Scripts/fix_libfido2_framework.sh, Scripts/increment_build_number.sh, Scripts/export_options.plist. Multiple shell scripts in the Scripts directory are executed during build and release processes. These could be vulnerable to path injection or command injection if not properly secured. Fix: Apply security hardening: (1) Use absolute paths in all scripts, (2) Add input validation and sanitization, (3) Use set -euo pipefail in bash scripts, (4) Implement code review for all build scripts, (5) Scan with shellcheck
• Medium · GitHub Actions Workflow Security — .github/workflows/ci.yml, .github/workflows/appcast.yml, .github/workflows/release-drafter.yml. CI/CD workflows present in .github/workflows directory require verification of secure practices, particularly for token management, artifact signing, and release processes. Fix: Verify workflow security: (1) Use GITHUB_TOKEN with minimal required permissions, (2) Pin action versions to specific commits, (3) Implement approval gates for releases, (4) Audit secret management, (5) Enable workflow approval requirements
• Medium · Appcast XML Signature Verification — AppCast/appcast.xml, AppCast/appcast_pre.xml, AppCast/_plugins/signature_filter.rb. The appcast.xml and appcast_pre.xml files are used for software updates. The signature_filter.rb plugin suggests custom signature handling, but the security of this implementation is unclear. Fix: Ensure: (1) Appcast updates are signed with Ed25519 or RSA-

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.