How to Run Palmier Pro Locally: Complete macOS Setup Guide

Clone the repository, run swift build, then execute ./scripts/dev.sh to launch a debug build with live log streaming on macOS 26.

Palmier Pro is an AI-native macOS video editor built with Swift 6.2, SwiftUI, and AVFoundation. To run the Palmier Pro project locally, you need a Swift Package Manager-based workflow that compiles the executable target, builds Metal shaders via a custom plugin, and bundles resources for the GPU-accelerated video pipeline.

Prerequisites for Local Development

Before attempting to run Palmier Pro locally, ensure your development environment meets the following requirements:

• macOS 26 (Tahoe) on Apple Silicon – The Package.swift specifies .macOS(.v26) as the minimum platform target.
• Xcode 16 or later – Required for the Swift 6.2 toolchain and macOS SDK support.
• Command-line tools – Verify swift, git, and bash are available in your $PATH.

The app cannot run on Intel Macs or macOS versions earlier than 26 due to platform-specific APIs and Swift 6.2 dependencies.

Clone the Palmier Pro Repository

Download the source code from the palmier-io/palmier-pro repository:

git clone https://github.com/palmier-io/palmier-pro
cd palmier-pro

This creates a local copy of the Swift package, including the Sources/PalmierPro directory containing the UI and video editing logic, as well as the Metal/ directory for GPU kernels.

Build and Run Palmier Pro Locally

You have three primary methods to compile and launch the application. Choose based on whether you need a quick test or a full debuggable bundle.

Option 1: Quick Swift Build

For rapid iteration without bundling, use Swift Package Manager directly:

swift build
swift run PalmierPro

What happens: swift build reads Package.swift, resolves dependencies (MCP, Sparkle, Sentry, Clerk, Convex, Tokenizers, Lottie), and compiles the executable. The MetalCIKernelPlugin automatically builds .metallib files from sources in Metal/ before linking. swift run executes the binary from .build/debug/PalmierPro.

Option 2: Debug Bundle with Log Streaming (Recommended)

For development with console visibility into OSLog messages, use the provided helper script:

./scripts/dev.sh

To disable the log stream and launch only:

./scripts/dev.sh --no-stream

What happens: The scripts/dev.sh script invokes scripts/bundle.sh debug --fast to assemble .build/PalmierPro.app, injects a minimal Info.plist, performs ad-hoc code signing, and launches the app. While running, it streams logs matching the subsystem io.palmier.pro to your terminal, making it ideal for debugging the MCP server (running on 127.0.0.1:19789) or video pipeline issues.

Option 3: Run the Test Suite

Validate functionality before running the full application:

swift test

This executes the PalmierProTests target, covering video project loading, caption handling, AI tool integration, and UI behaviors.

Understanding the Local Build Architecture

To troubleshoot effectively, understand how the components interact:

• Package.swift – Defines the executable product PalmierPro, declares third-party dependencies, and registers the MetalCIKernelPlugin as a build-tool plugin for GPU-accelerated effects.
• Plugins/MetalCIKernelPlugin/MetalCIKernelPlugin.swift – Compiles .metal source files (e.g., for Vignette and HueCurves effects) into .metallib libraries during the build process.
• Sources/PalmierPro/ – Contains SwiftUI views, AppKit integrations, AVFoundation video logic, and bundled resources (fonts, images, Lottie files, MCP bundles).
• scripts/bundle.sh – Handles resource copying, app bundle structure creation, and code signing.

Troubleshooting Common Local Build Issues

Issue	Cause	Solution
"requires macOS 26" build error	Running on older macOS version	Upgrade to macOS 26 (Tahoe) or use a compatible VM
Missing Metal shaders (.metallib not found)	Plugin execution failed	Clean build with swift package clean then rebuild; verify MetalCIKernelPlugin runs during build
Launch crash with missing key errors	Info.plist variables (e.g., CLERK_PUBLISHABLE_KEY) undefined	For local development, these warnings are non-fatal unless you access those specific code paths; production builds require proper keys
"Command not found: log" when streaming	macOS version predates the log CLI (introduced in macOS 12)	Run with --no-stream flag or upgrade macOS

Summary

• Requirements: macOS 26, Xcode 16, Apple Silicon Mac.
• Clone: git clone https://github.com/palmier-io/palmier-pro.
• Quick run: swift build && swift run PalmierPro.
• Development: ./scripts/dev.sh for debug bundles with log streaming.
• Testing: swift test to verify functionality.
• Architecture: The MetalCIKernelPlugin in Plugins/ is essential for GPU effects, while scripts/bundle.sh handles app packaging.

Frequently Asked Questions

What are the exact system requirements to run Palmier Pro locally?

You need macOS 26 (Tahoe) running on Apple Silicon (M1 or later), plus Xcode 16 for the Swift 6.2 toolchain. The Package.swift explicitly targets .macOS(.v26), and the codebase uses Swift 6.2 features unavailable in earlier versions. Intel-based Macs are not supported.

Why does the build fail with "requires macOS 26"?

This error occurs when your host system is running macOS 15 or earlier. The Package.swift manifest declares a platform requirement that Swift Package Manager enforces strictly. You must upgrade to the macOS 26 developer beta or final release, or use a remote build environment that supports the required SDK.

How do I debug Palmier Pro if it crashes on launch?

Run the ./scripts/dev.sh command without the --no-stream flag to capture OSLog output in real-time. Look for subsystem io.palmier.pro messages that indicate where the initialization fails. Common causes include missing Metal shader libraries (ensure the MetalCIKernelPlugin completed successfully) or missing API keys for services like Clerk or Sentry, though the app typically handles missing keys gracefully in debug builds until those specific features are accessed.

Can I run Palmier Pro on Intel Macs?

No. The project is configured for Apple Silicon architectures only, and dependencies such as the Metal compute shaders and specific AVFoundation optimizations require ARM64. Attempting to build on Intel hardware will fail during the compilation phase or produce non-functional binaries.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}