# Developing macOS Applications with SwiftUI or AppKit Plugins: A Complete Guide to the Build macOS Apps Plugin

> Build macOS apps with SwiftUI or AppKit plugins. Discover a shell-first workflow combining modern patterns with AppKit interoperability. Your complete guide to native macOS development.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: how-to-guide
- Published: 2026-06-27

---

**The Build macOS Apps plugin provides a shell-first development workflow for native macOS applications, combining SwiftUI patterns with AppKit interoperability through a skill-based architecture.**

The OpenAI plugins repository ships a production-ready toolchain for **developing macOS applications with SwiftUI or AppKit plugins**. The Build macOS Apps plugin implements a **skill-first design** that separates UI composition from build automation, allowing developers to scaffold projects, wire debugging workflows, and bridge between SwiftUI and AppKit using concrete reference implementations.

## Plugin Architecture and Skill Structure

The plugin follows the **Codex-plugin conventions** established across the openai/plugins repository, organizing capabilities into self-contained units rather than monolithic configurations.

### Plugin Manifest and Metadata

Every plugin begins with a canonical manifest at [`plugins/build-macos-apps/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/build-macos-apps/.codex-plugin/plugin.json). This file defines the plugin name, version, description, keywords, and the location of its skills. The manifest serves as the entry point for the Codex system to discover available capabilities.

### Skill-First Design Pattern

Each capability lives as a **self-contained skill** under `plugins/build-macos-apps/skills/`. This modular approach isolates concerns:

- **SwiftUI Patterns** – macOS-specific scene composition (windows, menus, settings, split views)
- **Build-Run-Debug** – Shell-first automation for compiling and launching
- **AppKit Interop** – Bridging helpers for representables and responder-chain integration

Every skill ships a `references/` directory containing markdown files with concrete API snippets. For example, [`references/windowing.md`](https://github.com/openai/plugins/blob/main/references/windowing.md) and [`references/menu-bar-extra.md`](https://github.com/openai/plugins/blob/main/references/menu-bar-extra.md) capture platform-specific patterns that differ from iOS implementations.

## SwiftUI Patterns for macOS

The **SwiftUI Patterns skill** (located at [`plugins/build-macos-apps/skills/swiftui-patterns/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/build-macos-apps/skills/swiftui-patterns/SKILL.md)) provides guidance for macOS-centric scene composition. Unlike iOS applications, macOS apps require explicit handling of multiple windows, menu-bar extras, and system-adaptive colors.

The skill emphasizes using `@SceneStorage` and `@AppStorage` for state persistence, and defines canonical patterns for `Settings` scenes and `WindowGroup` configurations. Reference files in `plugins/build-macos-apps/skills/swiftui-patterns/references/` contain copy-pasteable implementations for complex layouts like three-column navigation and inspector sidebars.

## Build, Run, and Debug Workflow

The **Build-Run-Debug skill** implements a **shell-first model** where Xcode discovery, compilation, signing, and notarization are handled by scripts rather than IDE configurations.

### The Shell-First Model

The heavy lifting is performed by [`script/build_and_run.sh`](https://github.com/openai/plugins/blob/main/script/build_and_run.sh), generated according to the canonical shape defined in [`plugins/build-macos-apps/skills/build-run-debug/references/run-button-bootstrap.md`](https://github.com/openai/plugins/blob/main/plugins/build-macos-apps/skills/build-run-debug/references/run-button-bootstrap.md). This script handles Xcode workspace detection, `xcodebuild` or `swift build` execution, and app bundle launching.

Configure the Codex Run button by creating [`.codex/environments/environment.toml`](https://github.com/openai/plugins/blob/main/.codex/environments/environment.toml):

```bash
cat > .codex/environments/environment.toml <<'EOF'
[actions.run]
command = "./script/build_and_run.sh"
description = "Build, run and debug the macOS app"
EOF

```

The script itself follows a strict contract for debugging and telemetry:

```bash
#!/usr/bin/env bash
set -e

# 1️⃣ Kill any running instance

pkill -x MyApp || true

# 2️⃣ Build the macOS target (Xcode workspace or SwiftPM)

if [ -f MyApp.xcworkspace ]; then
    xcodebuild -workspace MyApp.xcworkspace -scheme MyApp -configuration Release -quiet
else
    swift build -c release
fi

# 3️⃣ Launch the app bundle

open -n ./dist/MyApp.app

```

Flags for `--logs` and `--telemetry` extend this workflow for continuous debugging sessions without manual terminal management.

## AppKit Interoperability

When SwiftUI cannot express required desktop behaviors, the **AppKit Interop skill** (at [`plugins/build-macos-apps/skills/appkit-interop/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/build-macos-apps/skills/appkit-interop/SKILL.md)) provides escape hatches via `NSViewRepresentable` and `NSViewControllerRepresentable`.

The skill covers responder-chain integration, custom panels, and drag-drop implementations using `NSPasteboard`. Reference files like [`references/window-panels.md`](https://github.com/openai/plugins/blob/main/references/window-panels.md) and [`references/drag-drop-pasteboard.md`](https://github.com/openai/plugins/blob/main/references/drag-drop-pasteboard.md) contain concrete implementations.

Bridge to AppKit using `NSViewRepresentable` for custom panels:

```swift
import SwiftUI
import AppKit

struct CustomPanelRepresentable: NSViewRepresentable {
    func makeNSView(context: Context) -> NSPanel {
        let panel = NSPanel(contentRect: NSRect(x: 0, y: 0, width: 400, height: 300),
                           styleMask: [.titled, .closable],
                           backing: .buffered,
                           defer: false)
        panel.title = "Custom Panel"
        return panel
    }

    func updateNSView(_ nsView: NSPanel, context: Context) {
        // Update panel content if needed
    }
}

```

Use this within SwiftUI views via `sheet` or conditional presentation, maintaining the declarative pattern while accessing AppKit's imperative APIs.

## Project Structure and Scaffolding

Scaffold a new macOS project using the directory conventions recognized by the build scripts:

```bash

# Create the folder layout

mkdir -p MyApp/App MyApp/Views MyApp/Models MyApp/Stores MyApp/Services MyApp/Support script

# Minimal @main entry point (App/MyAppApp.swift)

cat > MyApp/App/MyAppApp.swift <<'EOF'
import SwiftUI

@main
struct MyAppApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
        }
        Settings {
            SettingsView()
        }
    }
}
EOF

```

Add a Settings scene using the SwiftUI Patterns conventions:

```swift
// Views/SettingsView.swift
struct SettingsView: View {
    var body: some View {
        Form {
            Toggle("Enable feature", isOn: .constant(true))
        }
        .frame(width: 300)
    }
}

```

Command files in `plugins/build-macos-apps/commands/` expose these workflows to the Codex-MCP surface, enabling one-click execution from the UI without terminal interaction.

## Summary

- The **Build macOS Apps plugin** provides a complete toolchain for native macOS development within the OpenAI plugins ecosystem.
- **Skill-first architecture** separates SwiftUI patterns, build automation, and AppKit bridging into modular components.
- **Shell-first workflows** delegate compilation and signing to [`script/build_and_run.sh`](https://github.com/openai/plugins/blob/main/script/build_and_run.sh), keeping UI code clean and focused.
- **AppKit Interop** offers concrete patterns for `NSViewRepresentable` implementations when SwiftUI's native APIs are insufficient.
- Reference materials in each skill's `references/` directory provide copy-pasteable implementations for complex macOS-specific behaviors.

## Frequently Asked Questions

### What is the Build macOS Apps plugin?

The Build macOS Apps plugin is a Codex-compatible development toolchain within the openai/plugins repository that provides automated workflows for building, running, and debugging native macOS applications. It ships three primary skills—SwiftUI Patterns, Build-Run-Debug, and AppKit Interop—each containing reference implementations and shell scripts for specific development tasks.

### How does the shell-first build workflow work?

The shell-first model delegates all build operations to [`script/build_and_run.sh`](https://github.com/openai/plugins/blob/main/script/build_and_run.sh), which detects Xcode workspaces or Swift Package Manager projects and executes the appropriate build commands. This script handles killing running instances, compiling with `xcodebuild` or `swift build`, and launching the resulting `.app` bundle. The Codex Run button is wired via [`.codex/environments/environment.toml`](https://github.com/openai/plugins/blob/main/.codex/environments/environment.toml), pointing to this script for one-click execution.

### When should I use AppKit interop instead of pure SwiftUI?

Use **AppKit Interop** when implementing behaviors that SwiftUI cannot express natively on macOS, such as custom `NSPanel` configurations, complex drag-and-drop pasteboard operations, responder-chain integration, or menu-bar extras. The skill provides `NSViewRepresentable` implementations that bridge SwiftUI's declarative syntax with AppKit's imperative APIs.

### How do I configure the Codex Run button for macOS development?

Create [`.codex/environments/environment.toml`](https://github.com/openai/plugins/blob/main/.codex/environments/environment.toml) in your project root with an `[actions.run]` section specifying the path to [`script/build_and_run.sh`](https://github.com/openai/plugins/blob/main/script/build_and_run.sh). Copy the canonical script from [`plugins/build-macos-apps/skills/build-run-debug/references/run-button-bootstrap.md`](https://github.com/openai/plugins/blob/main/plugins/build-macos-apps/skills/build-run-debug/references/run-button-bootstrap.md), customize it for your app name and build configuration, and mark it executable with `chmod +x`. The Codex UI will then display a Run button that executes your build workflow.