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

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. 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 and 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) 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, generated according to the canonical shape defined in 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:

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:

#!/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) 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 and references/drag-drop-pasteboard.md contain concrete implementations.

Bridge to AppKit using NSViewRepresentable for custom panels:

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:

# 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:

// 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, 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, 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, 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 in your project root with an [actions.run] section specifying the path to script/build_and_run.sh. Copy the canonical script from 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.

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