build-macos-apps — Claude plugin for building macOS apps
A Claude plugin bundling macOS-first workflows: build, run, test, debug, sign and instrument local desktop apps.
Open on GitHubWhat build-macos-apps does
The plugin lives in plugins/build-macos-apps and gathers macOS workflows into one skill set. Eleven skills ship inside: build-run-debug, test-triage, signing-entitlements, swiftpm-macos, packaging-notarization, swiftui-patterns, liquid-glass, window-management, appkit-interop, view-refactor, telemetry.
The default posture is shell-first. Skills discover local Xcode workspaces, projects and Swift packages, then build and run apps through xcodebuild, swift, open, lldb, codesign, spctl, plutil and log stream. The plugin also creates a project-local script/build_and_run.sh and wires .codex/environments/environment.toml so the Run button in the Claude app works.
There is a desktop UI layer too: SwiftUI scenes, menus, settings, toolbars, multiwindow flows, AppKit bridges via representables and the responder chain, plus refactoring of large view files. Instrumentation uses Logger and os.Logger for windows, sidebars and menu commands, verified with Console and log stream. What it does not cover: iOS, watchOS or tvOS simulator control, desktop UI automation, App Store Connect releases, design-system generation. If your target is an iOS app, this is the wrong plugin — look at plugins/build-ios-apps instead.
No plugin-local .mcp.json ships here; at the plugin level it stays skills-first.
What it helps with
- build and run a macOS app from the shell without clicking through Xcode
- triage a launch failure, crash or linker error
- read runtime events with
log streamand Console - check signing identities, entitlements and hardened runtime
- prepare packaging and notarization for distribution
Example prompts for the agent
- build and run this macOS app, find the workspace yourself
- the UI-hosted tests are failing — figure out why
- add os.Logger instrumentation to windows and menu commands
Questions about build-macos-apps
How do I install build-macos-apps in Claude?
The plugin sits in the openai/plugins repository under plugins/build-macos-apps. Copy it into your project or wire it up as a Claude plugin following its structure: the .codex-plugin/plugin.json manifest points Claude at the plugin contents.
What does build-macos-apps do?
It gives Claude a set of skills for local macOS development: building and running, test triage, signing and entitlements, SwiftPM, packaging and notarization, SwiftUI patterns, window management, AppKit interop, view refactoring and telemetry.
How is build-macos-apps different from build-ios-apps?
It does not assume simulator tooling or touch-driven UI inspection. The core model is shell-first on xcodebuild, swift, lldb and codesign, with a native SwiftUI and AppKit layer on top. iOS, watchOS and tvOS are out of scope.
Source text
build-macos-apps · MIT
# Build macOS Apps Plugin
This plugin packages macOS-first development workflows in `plugins/build-macos-apps`.
It currently includes these skills:
- `build-run-debug`
- `test-triage`
- `signing-entitlements`
- `swiftpm-macos`
- `packaging-notarization`
- `swiftui-patterns`
- `liquid-glass`
- `window-management`
- `appkit-interop`
- `view-refactor`
- `telemetry`
## What It Covers
- discovering local Xcode workspaces, projects, and Swift packages
- building and running macOS apps with shell-first desktop workflows
- creating one project-local `script/build_and_run.sh` entrypoint and wiring `.codex/environments/environment.toml` so the Codex app Run button works
- implementing native macOS SwiftUI scenes, menus, settings, toolbars, and multiwindow flows
- adopting modern macOS Liquid Glass and design-system guidance with standard SwiftUI structures, toolbars, search, controls, and custom glass surfaces
- tailoring SwiftUI windows with title/toolbar styling, material-backed container backgrounds, minimize/restoration behavior, default and ideal placement, borderless window style, and launch behavior
- bridging into AppKit for representables, responder-chain behavior, panels, and other desktop-only needs
- refactoring large macOS view files toward stable scene, selection, and command structure
- adding lightweight `Logger` / `os.Logger` instrumentation for windows, sidebars, menu commands, and menu bar actions
- reading and verifying runtime events with Console, `log stream`, and process logs
- triaging failing unit, integration, and UI-hosted macOS tests
- debugging launch failures, crashes, linker problems, and runtime regressions
- inspecting signing identities, entitlements, hardened runtime, and Gatekeeper issues
- preparing packaging and notarization workflows for distribution
## What It Does Not Cover
- iOS, watchOS, or tvOS simulator control
- desktop UI automation
- App Store Connect release management
- pixel-perfect visual design or design-system generation
## Plugin Structure
The plugin lives at:
- `plugins/build-macos-apps/`
with this shape:
- `.codex-plugin/plugin.json`
- required plugin manifest
- defines plugin metadata and points Codex at the plugin contents
- `agents/`
- plugin-level agent metadata
- currently includes `agents/openai.yaml` for the OpenAI surface
- `commands/`
- reusable workflow entrypoints for common macOS development tasks
- `skills/`
- the actual skill payload
- each skill keeps the normal skill structure (`SKILL.md`, optional
`agents/`, `references/`, `assets/`, `scripts/`)
## Notes
This plugin is currently skills-first at the plugin level. It does not ship a
plugin-local `.mcp.json`, matching the public `plugins/build-ios-apps` shape.
The default posture is shell-first. Unlike the iOS build plugin, this plugin
does not assume simulator tooling or touch-driven UI inspection for its main
workflows. The core execution model leans on `xcodebuild`, `swift`, `open`,
`lldb`, `codesign`, `spctl`, `plutil`, and `log stream`, with a compact desktop
UI layer for native SwiftUI scene design, AppKit interop, and macOS-specific
refactoring.
© OpenAI · MIT · openai/plugins
