This page contains 7 additions and 116 deletions.
Need
Build and packaging
Default options
xcodebuild, swift build, and App Store Connect CLI
Why it's needed
Keep local builds, manual archives, script-based notarization, and App Store uploads in a repeatable terminal-first loop.
11name: Build for macOS# Build for macOS | Codex use cases
2tagline: Use Codex to scaffold, build, and debug native Mac apps with SwiftUI.
3summary: Use Codex to build macOS SwiftUI apps, wire a shell-first build-and-run
4 loop, and add desktop-native scene, window, AppKit, and signing workflows as
5 the app matures.
6skills:
7 - token: build-macos-apps
8 url: https://github.com/openai/plugins/tree/main/plugins/build-macos-apps
9 description: Build and debug macOS apps with shell-first workflows, design
10 desktop-native SwiftUI scenes and windows, bridge to AppKit where needed,
11 and prepare signing and notarization paths.
12bestFor:
13 - Greenfield macOS SwiftUI apps where you want Codex to scaffold a
14 desktop-native app shell and repeatable build script
15 - Existing Mac apps where Codex needs to work on windows, menus, sidebars,
16 settings, AppKit interop, or signing issues
17 - Teams that want macOS work to stay shell-first while still respecting native
18 desktop UX conventions
19starterPrompt:
20 title: Scaffold a Native Mac App
21 body: >-
22 Use the Build macOS Apps plugin to scaffold a starter macOS SwiftUI app and
23 add a project-local `script/build_and_run.sh` entrypoint I can wire to a
24 `Run` action.
25 2
3Need
26 4
275 Constraints:Build and packaging
28 6
297 - Stay shell-first. Prefer `xcodebuild` for Xcode projects and `swift build`Default options
30 for package-first apps.
31 8
329 - Model Mac scenes explicitly with a main window plus `Settings`,`xcodebuild`, `swift build`, and [App Store Connect CLI](https://asccli.sh/)
33 `MenuBarExtra`, or utility windows only when they fit the product.
34 10
3511 - Prefer desktop-native sidebars, toolbars, menus, keyboard shortcuts, andWhy it's needed
36 system materials over iOS-style push navigation.
37 12
3813 - Use a narrow AppKit bridge only when SwiftUI cannot express the desktopKeep local builds, manual archives, script-based notarization, and App Store uploads in a repeatable terminal-first loop.
39 behavior cleanly.
40 14
41 - Keep one small validation loop for each change and tell me exactly which
42 build, launch, or log commands you ran.
43
44
45 Deliver:
46
47 - the app scaffold or requested Mac feature slice
48
49 - a reusable build-and-run script
50
51 - the smallest validation steps you ran
52
53 - any desktop-specific follow-up work you recommend
54relatedLinks:
55 - label: Model Context Protocol
56 url: /codex/mcp
57 - label: Agent skills
58 url: /codex/skills
59techStack:
60 - need: UI framework
61 goodDefault: "[SwiftUI](https://developer.apple.com/documentation/swiftui/)"
62 why: A strong default for windows, sidebars, toolbars, settings, and
63 scene-driven Mac app structure.
64 - need: AppKit bridge
65 goodDefault: "[AppKit](https://developer.apple.com/documentation/appkit)"
66 why: Use small `NSViewRepresentable`, `NSViewControllerRepresentable`, or
67 `NSWindow` bridges when SwiftUI stops short of a desktop behavior you
68 need.
69 - need: Build and packaging
70 goodDefault: "`xcodebuild`, `swift build`, and [App Store Connect
71 CLI](https://asccli.sh/)"
72 why: Keep local builds, manual archives, script-based notarization, and App
73 Store uploads in a repeatable terminal-first loop.
74
75## Scaffold the app and build loop
76
77For a new Mac app, ask Codex to choose the right scene model first: `WindowGroup`, `Window`, `Settings`, `MenuBarExtra`, or `DocumentGroup`. That keeps the app desktop-native from the first pass instead of growing from an iOS-style `ContentView`.
78
79Keep the execution loop shell-first. For Xcode projects, use `xcodebuild`. For package-first apps, use `swift build` and a project-local `script/build_and_run.sh` wrapper that stops the old process, builds the app, launches the new artifact, and can optionally expose logs or telemetry.
80
81If a pure SwiftPM app is a GUI app, bundle and launch it as a `.app` instead of running the raw executable directly. That avoids missing Dock, activation, and bundle-identity issues during local validation.
82
83## Leverage skills
84
85Add the [Build macOS Apps plugin](https://github.com/openai/plugins/tree/main/plugins/build-macos-apps) once the work gets more desktop-specific. It covers shell-first build and debug loops, SwiftPM app packaging, native SwiftUI scene and window patterns, AppKit interop, unified logging, test triage, and signing/notarization workflows.
86
87To learn more about how to install and use plugins and skills, see the [Codex plugins documentation](https://developers.openai.com/codex/plugins) and [skills documentation](https://developers.openai.com/codex/skills).
88
89## Build desktop-native UI
90
91Prefer Mac conventions over iOS navigation patterns. Use `NavigationSplitView` for sidebar/detail layouts, explicit `Settings` scenes for preferences, toolbars and commands for discoverable actions, and menu bar extras for lightweight always-available utilities.
92
93Use system materials, semantic colors, and standard controls first. Add custom window styling, drag regions, or Liquid Glass surfaces only when the product needs a distinct desktop surface.
94
95If SwiftUI gets close but not all the way there, add the smallest possible AppKit bridge. Good examples are open/save panels, first-responder control, menu validation, drag-and-drop edges, and a wrapped `NSView` for one specialized control.
96
97## Debug, test, and prepare for shipping
98
99For runtime behavior, ask Codex to add a few `Logger` events around window opening, sidebar selection, menu commands, or background sync, then verify those events with `log stream` after the app launches.
100
101For failing tests, have Codex run the smallest useful `xcodebuild test` or `swift test` scope first and classify whether the issue is compilation, an assertion failure, a crash, a flake, or an environment/setup problem.
102
103When the work shifts from local iteration to distribution, ask Codex to prepare both a manual archive path in Xcode and a script-based archive and notarization path for repeatable shipping. Have it inspect the app bundle, entitlements, and hardened runtime with `codesign` and `plutil`, and use [App Store Connect CLI](https://asccli.sh/) when you want uploads to stay in the terminal too.
104
105## Example prompt
106
107## Practical tips
108
109### Keep scenes explicit
110
111Model the main window, settings window, utility windows, and menu bar extras as separate scene roots instead of hiding the whole app inside one giant view.
112
113### Let system chrome do more of the work
114
115Before creating custom sidebars, toolbars, or materials, check whether standard SwiftUI scene and window APIs already give you the Mac behavior you want.
116
117### Treat AppKit as a narrow edge
118
119Use `NSViewRepresentable`, `NSViewControllerRepresentable`, or a focused `NSWindow` helper for one missing desktop capability, but keep SwiftUI as the source of truth for selection and app state.
120
121### Validate signing and notarization separately from local build success
122
123A successful local launch does not prove the app is signed or notarization-ready. Keep a manual Xcode archive flow for one-off release checks, add a scripted archive and notarization flow for repeatable distribution, and run `codesign` and `plutil` checks when the task is about shipping, not just local iteration.
