How to Set Up a Development Environment for Palmier Pro: Complete Guide

Setting up a Palmier Pro development environment requires macOS 26 on Apple Silicon, Xcode 16 with Swift 6.2, and the command line tools to build the Swift package using swift build or the ./scripts/dev.sh helper for live debugging.

Palmier Pro is an AI-native macOS video editor built with SwiftUI, AppKit, and AVFoundation. This guide walks you through the complete process of configuring your local development environment for the palmier-io/palmier-pro repository, from system prerequisites to understanding the modular architecture.

Prerequisites

Before building the project, ensure your system meets the following requirements:

• macOS 26 (Tahoe) on Apple Silicon — The app targets the newest macOS SDK and uses platform-specific APIs that require Apple Silicon chips.
• Xcode 16+ with Swift 6.2 toolchain — The Package.swift file declares swift-tools-version: 6.2 and depends on features only available in Xcode 16.
• Git — Required to clone the repository and manage version control.
• Command-line tools — Ensure swift and xcodebuild are available in your PATH.

If you have multiple Swift toolchains installed, select the 6.2 toolchain via Xcode → Preferences → Components.

Clone the Repository

Start by cloning the repository to your local machine:

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

The repository contains the complete source tree under Sources/ and a comprehensive test suite under Tests/.

Build and Run the Application

Quick Build and Run

Use the following commands to compile and launch the application directly:

swift build
swift run PalmierPro

The swift build command reads the package definition in Package.swift and pulls third-party dependencies including DSWaveformImage, Sparkle, and Sentry. The swift run PalmierPro command executes the product defined as executable(name: "PalmierPro", ...).

Development Build with Live Logging

For active development with debug output streaming to your terminal, use the provided helper script:

./scripts/dev.sh

This script, located at scripts/dev.sh, builds a debug-signed bundle, launches the application, and streams OSLog output to the terminal. This is the recommended approach when you need to see debug prints from the Log.bootstrap() initialization in App/main.swift.

Project Architecture Overview

Palmier Pro follows a modular architecture combining SwiftUI and AppKit. The codebase is organized into distinct layers with clear separation of concerns:

Application Bootstrap and State

The entry point at App/main.swift bootstraps logging, initializes telemetry, loads custom fonts, and launches the NSApplication. Global application state is managed by AppState, a singleton defined in App/AppState.swift that tracks the active VideoProject, manages the MCP service lifecycle, and handles project operations (new, open, close).

UI Design System

Visual consistency is enforced through UI/AppTheme.swift, which defines all spacing, fonts, colors, radii, and shadows. UI components never hard-code numeric values, instead referencing the centralized theme.

Core Editing Components

• Timeline — The video editing surface is implemented in Timeline/TimelineView.swift, handling clip rendering, the snap-engine, drag state, and user interactions.
• Preview — Real-time frame rendering and compositing occur in Preview/PreviewView.swift, which manages the export pipelines and Lottie integrations.
• Project Model — Project/VideoProject.swift owns the editor view model, media assets, and persists the .palmier bundle format.

AI Agent Integration

The application exposes a local HTTP endpoint at http://127.0.0.1:19789/mcp via Agent/AgentService.swift, allowing external agents such as Claude or Cursor to drive the editor programmatically.

Utilities and Logging

Shared utilities including the logging system (Log.swift), disk caching, keychain storage, and image encoding reside in the Utilities directory. The logging implementation in Utilities/Log.swift supports the debug output captured by the development script.

Running Tests

Validate your setup and ensure code correctness by running the unit test suite:

swift test

The test suite covers transcription, rendering, and timeline geometry. For example, transform and crop logic is validated in Tests/PalmierProTests/Rendering/TransformCropTests.swift.

Development Workflow Commands

Task	Command	Description
Update dependencies	swift package update	Pulls the latest versions of packages listed in Package.swift.
Run specific tests	swift test -v -t <TestName>	Executes a specific XCTest target with verbose output.
Release build	./scripts/release.sh <tag>	Packages the app into a signed DMG for distribution (CI workflow).

Summary

• Palmier Pro requires macOS 26 and Xcode 16+ with Swift 6.2 to build the Swift package correctly.
• Clone the repository and use swift build or ./scripts/dev.sh to compile and run.
• Architecture follows SwiftUI + AppKit patterns with modular separation into App, UI, Timeline, Preview, Project, and Agent layers.
• Key entry points include App/main.swift for bootstrapping and App/AppState.swift for global state management.
• Testing is available via swift test with coverage for rendering and timeline logic.

Frequently Asked Questions

Can I develop Palmier Pro on an Intel-based Mac?

No. According to the README and source code requirements, Palmier Pro requires macOS 26 on Apple Silicon specifically. The codebase utilizes platform-specific APIs and optimizations that depend on Apple Silicon architecture.

Why does the build fail with "package requires swift-tools-version 6.2"?

This error indicates you are using an older Xcode version. You must install Xcode 16 or later, which includes the Swift 6.2 toolchain required by the Package.swift manifest. Verify your toolchain version by running swift --version in the terminal.

How do I debug the MCP server integration?

The MCP server runs locally on port 19789 as implemented in Agent/AgentService.swift. To debug interactions, run the application using ./scripts/dev.sh to enable live logging, then monitor the OSLog output for incoming HTTP requests and agent commands. You can test the endpoint by sending requests to http://127.0.0.1:19789/mcp while the app is running.

Where are the test files located and how do I run a specific test?

Test files are located in the Tests/PalmierProTests/ directory. To run a specific test, use the command swift test -v -t <TestClassName>, replacing <TestClassName> with the specific test target you want to execute, such as TransformCropTests for rendering validation.

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