How to Set Up Palmier Pro Locally: Complete macOS Build Guide

Clone the repository, ensure you have macOS 26 (Tahoe) on Apple Silicon with Xcode 16+, then run ./scripts/dev.sh to build the debug bundle and launch the app.

Palmier Pro is an open-source, Swift-native video editor designed exclusively for macOS 26 (Tahoe) running on Apple Silicon. Setting up Palmier Pro locally requires the Swift 6.2 toolchain and a standard Swift Package Manager (SPM) workflow to compile the executable target into a macOS .app bundle.

Prerequisites for Local Development

Before building Palmier Pro locally, verify your environment meets these strict requirements:

• macOS 26+ (Tahoe) on Apple Silicon – The project targets macOS 26 explicitly and requires Apple Silicon architecture according to the README.md at lines 11-13.
• Xcode 16+ with Swift 6.2 toolchain – Required for compilation as specified in CONTRIBUTING.md lines 12-14.
• Internet connectivity – SPM must fetch dependencies from GitHub during the initial build.

Clone and Build the Repository

Start by cloning the repository and verifying your Swift toolchain version:

git clone https://github.com/palmier-io/palmier-pro.git
cd palmier-pro
swift --version  # Should report Swift 6.2

Compile the project using Swift Package Manager. The Package.swift file declares the executable target and platform constraints at lines 5-22:

swift build

To run the binary directly without bundling:

swift run PalmierPro

Development Workflow with Debug Scripts

For rapid iteration, use the provided helper scripts rather than manual builds. The scripts/dev.sh file automates building a debug bundle, launching the app, and streaming OSLog output.

Execute the development script:

./scripts/dev.sh

This script internally calls scripts/bundle.sh debug --fast to produce a fast-debug bundle, then opens .build/PalmierPro.app and streams logs for debugging. To launch without log streaming:

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

Understanding the Project Structure

Key architectural components impact how you navigate and modify the codebase:

Centralized UI Styling

All visual constants live in Sources/PalmierPro/UI/AppTheme.swift. Every view imports AppTheme to reference standardized colors, spacing, fonts, and shadows, avoiding hard-coded values across the UI. The file defines constants like AppTheme.Spacing.md, AppTheme.Background.raisedColor, and AppTheme.Radius.sm at lines 4-30.

MCP Server Integration

When Palmier Pro launches, it starts an HTTP MCP server at http://127.0.0.1:19789/mcp. This enables AI agents (Claude, Codex, Cursor) to interact with the video timeline programmatically. The server implementation resides under Sources/PalmierPro/ and leverages the swift-sdk dependency.

Build Configuration

The Package.swift file manages several critical build aspects:

• Dependencies – Third-party packages including DSWaveformImage (audio waveforms), Sparkle (auto-updates), Sentry (crash reporting), Clerk (authentication), and Convex (backend).
• Metal Shaders – The MetalCIKernelPlugin compiles .metal shader files (e.g., Vignette.metal, Grain.metal) declared in the target's plugins array at lines 49-51.
• Resources – Fonts, images, and MCP bundles are packaged via the resources array at lines 43-48.

Running the Test Suite

Validate your local setup by executing the unit tests:

swift test

This runs the full test suite located in the Tests/ directory to ensure all modules compile and function correctly on your machine.

Troubleshooting Common Setup Issues

Symptom	Likely Cause	Solution
Build fails with toolchain errors	Xcode version older than 16	Install Xcode 16+ or select the correct Swift 6.2 toolchain
swift build hangs indefinitely	Network proxy blocking GitHub	Ensure outbound HTTPS to github.com is allowed for SPM
App crashes on launch	Code signing or entitlements	Run the built .app directly from .build/; the project is non-sandboxed
No log output in terminal	OSLog streaming disabled	Use ./scripts/dev.sh without the --no-stream flag

Summary

• Palmier Pro requires macOS 26 (Tahoe) on Apple Silicon and Xcode 16+ with Swift 6.2 to build locally.
• Use ./scripts/dev.sh for the fastest development workflow, which handles debug builds, bundling, and log streaming automatically.
• The project uses Swift Package Manager exclusively; no CocoaPods or Carthage required.
• UI styling is centralized in Sources/PalmierPro/UI/AppTheme.swift for consistent design across views.
• The built-in MCP server starts automatically on port 19789 for AI agent integration.
• Metal shaders compile automatically via the MetalCIKernelPlugin during the build process.

Frequently Asked Questions

Can I run Palmier Pro on an Intel Mac or older macOS version?

No. According to the source code in README.md lines 11-13, Palmier Pro strictly requires macOS 26 (Tahoe) running on Apple Silicon. The codebase uses APIs and Swift 6.2 features incompatible with older macOS versions or Intel architecture.

What is the MCP server used for in local development?

The MCP (Model Context Protocol) server runs at http://127.0.0.1:19789/mcp when the app launches, enabling AI coding assistants like Claude, Codex, or Cursor to read and manipulate the video timeline programmatically. This facilitates AI-powered editing workflows directly within the Palmier Pro interface.

How are the Metal shaders compiled during the build process?

The Package.swift file includes a custom build-tool plugin called MetalCIKernelPlugin at lines 49-51. This plugin automatically compiles .metal shader files located in the Metal/ directory (such as Vignette.metal and Grain.metal) during the Swift build process, embedding them as resources in the final .app bundle.

Why does swift build fail with missing dependency errors?

SPM requires internet access to fetch dependencies like DSWaveformImage, Sparkle, and Sentry from GitHub. If the build hangs or fails with resolution errors, verify your network connection allows HTTPS traffic to github.com. Initial builds may take several minutes to download and compile all external packages.

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