use-cases/native-macos-apps.md +125 −0 added
1---
2name: Build for macOS
3tagline: Use Codex to scaffold, build, and debug native Mac apps with SwiftUI.
4summary: Use Codex to build macOS SwiftUI apps, wire a shell-first build-and-run
5 loop, and add desktop-native scene, window, AppKit, and signing workflows as
6 the app matures.
7skills:
8 - token: build-macos-apps
9 url: https://github.com/openai/plugins/tree/main/plugins/build-macos-apps
10 description: Build and debug macOS apps with shell-first workflows, design
11 desktop-native SwiftUI scenes and windows, bridge to AppKit where needed,
12 and prepare signing and notarization paths.
13bestFor:
14 - Greenfield macOS SwiftUI apps where you want Codex to scaffold a
15 desktop-native app shell and repeatable build script
16 - Existing Mac apps where Codex needs to work on windows, menus, sidebars,
17 settings, AppKit interop, or signing issues
18 - Teams that want macOS work to stay shell-first while still respecting native
19 desktop UX conventions
20starterPrompt:
21 title: Scaffold a Native Mac App
22 body: >-
23 Use the Build macOS Apps plugin to scaffold a starter macOS SwiftUI app and
24 add a project-local `script/build_and_run.sh` entrypoint I can wire to a
25 `Run` action.
26
27
28 Constraints:
29
30 - Stay shell-first. Prefer `xcodebuild` for Xcode projects and `swift build`
31 for package-first apps.
32
33 - Model Mac scenes explicitly with a main window plus `Settings`,
34 `MenuBarExtra`, or utility windows only when they fit the product.
35
36 - Prefer desktop-native sidebars, toolbars, menus, keyboard shortcuts, and
37 system materials over iOS-style push navigation.
38
39 - Use a narrow AppKit bridge only when SwiftUI cannot express the desktop
40 behavior cleanly.
41
42 - Keep one small validation loop for each change and tell me exactly which
43 build, launch, or log commands you ran.
44
45
46 Deliver:
47
48 - the app scaffold or requested Mac feature slice
49
50 - a reusable build-and-run script
51
52 - the smallest validation steps you ran
53
54 - any desktop-specific follow-up work you recommend
55relatedLinks:
56 - label: Model Context Protocol
57 url: /codex/mcp
58 - label: Agent skills
59 url: /codex/skills
60techStack:
61 - need: UI framework
62 goodDefault: "[SwiftUI](https://developer.apple.com/documentation/swiftui/)"
63 why: A strong default for windows, sidebars, toolbars, settings, and
64 scene-driven Mac app structure.
65 - need: AppKit bridge
66 goodDefault: "[AppKit](https://developer.apple.com/documentation/appkit)"
67 why: Use small `NSViewRepresentable`, `NSViewControllerRepresentable`, or
68 `NSWindow` bridges when SwiftUI stops short of a desktop behavior you
69 need.
70 - need: Build and packaging
71 goodDefault: "`xcodebuild`, `swift build`, and [App Store Connect
72 CLI](https://asccli.sh/)"
73 why: Keep local builds, manual archives, script-based notarization, and App
74 Store uploads in a repeatable terminal-first loop.
75---
76
77## Scaffold the app and build loop
78
79For 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`.
80
81Keep 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.
82
83If 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.
84
85## Leverage skills
86
87Add 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.
88
89To 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).
90
91## Build desktop-native UI
92
93Prefer 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.
94
95Use 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.
96
97If 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.
98
99## Debug, test, and prepare for shipping
100
101For 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.
102
103For 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.
104
105When 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.
106
107## Example prompt
108
109## Practical tips
110
111### Keep scenes explicit
112
113Model 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.
114
115### Let system chrome do more of the work
116
117Before creating custom sidebars, toolbars, or materials, check whether standard SwiftUI scene and window APIs already give you the Mac behavior you want.
118
119### Treat AppKit as a narrow edge
120
121Use `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.
122
123### Validate signing and notarization separately from local build success
124
125A 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.