Implementing SwiftUI Apps with the Build-iOS-Apps Plugin: A Complete Codex Guide

The Build-iOS-Apps plugin provides a modular toolkit of Codex skills that enables complete SwiftUI development—from scaffolding views with modern state patterns to profiling performance—directly within the OpenAI Codex environment.

This guide explores how to leverage the build-ios-apps plugin in the openai/plugins repository to design, build, and debug SwiftUI applications without leaving your Codex workflow. By invoking specific skills documented in individual SKILL.md files, developers can automate everything from Liquid Glass UI implementation to automated memory leak detection.

What Is the Build-iOS-Apps Plugin?

The Build-iOS-Apps plugin is a ready-made development environment located at plugins/build-ios-apps in the OpenAI plugins repository. It bundles nine specialized skills that each handle a distinct phase of iOS development, from defining App Intents to running ETTrace performance profiles.

According to the plugin manifest at .codex-plugin/plugin.json, the plugin registers capabilities including Interactive, Read, and Write operations, pointing Codex to the ./skills/ directory where individual toolkits reside. This architecture allows developers to invoke precise functionality—such as swiftui-ui-patterns for view composition or ios-simulator-browser for hot-reload previews—via simple API calls or natural language prompts.

Core Architecture and File Structure

Understanding the file layout is essential for navigating the plugin's capabilities and extending its functionality.

Plugin Manifest and Configuration

The entry point is .codex-plugin/plugin.json, which declares the plugin name, version (0.1.1), and skill directory location. Complementing this is .mcp.json, which configures the Multi-Channel Protocol (MCP) connection to XcodeBuildMCP, enabling build, run, and debug operations on iOS simulators without external tooling.

Skill Package Layout

Each skill follows a strict directory convention under plugins/build-ios-apps/skills/<skill-name>/:

skill/
├── SKILL.md              # Human-readable workflow and quick-start

├── agents/               # Optional surface-specific agents

├── references/           # Swift snippets, UI patterns, markdown docs

├── scripts/              # Helper automation (Python, Node, Bash)

└── assets/               # Icons and images

(Source: plugins/build-ios-apps/README.md)

Essential SwiftUI Development Skills

The plugin organizes functionality into discrete skills. Here are the critical ones for SwiftUI implementation.

SwiftUI UI Patterns (swiftui-ui-patterns)

This skill serves as the definitive reference for state ownership, navigation architecture, and sheet handling. Located at skills/swiftui-ui-patterns/SKILL.md, it mandates:

• Prefer @State/@Binding for local UI state (Rule 30)
• Use @Observable on iOS 17+, falling back to ObservableObject for earlier versions
• Reference implementations in references/components-index.md for NavigationStack, TabView, and sheet patterns

Liquid Glass Integration (swiftui-liquid-glass)

For iOS 26+ applications, this skill provides boilerplate for Apple's Liquid Glass APIs. The SKILL.md at skills/swiftui-liquid-glass/SKILL.md documents how to add the LiquidGlass Swift Package Manager dependency and implement GlassBackground views with proper availability guards.

Performance Audit (swiftui-performance-audit)

This skill automates profiling workflows using Instruments and ETTrace. It includes:

• profiling-intake.md: Instructions for attaching Instruments
• report-template.md: Auto-populated audit results
• code-smells.md: Checklists matched against view code during analysis

Simulator Browser (ios-simulator-browser)

Implements a hot-reload preview server via scripts/swiftui-preview-browser.mjs, exposing compiled SwiftUI previews over a local web server viewable within the Codex UI. This eliminates the need for constant Xcode rebuilds during UI iteration.

Practical Implementation Examples

The following patterns demonstrate how to apply the plugin's documented conventions in production SwiftUI code.

Example 1: State Ownership with NavigationStack

This pattern follows the swiftui-ui-patterns skill guidelines for narrow state definition and modern navigation:

import SwiftUI

// Define view-specific state as narrow as possible
struct SettingsView: View {
    @State private var enableNotifications = false   // local UI state
    
    var body: some View {
        Form {
            Toggle("Enable Notifications", isOn: $enableNotifications)
        }
    }
}

// Use NavigationStack per references/navigationstack.md
struct ContentView: View {
    var body: some View {
        NavigationStack {
            List {
                NavigationLink("Settings", destination: SettingsView())
            }
            .navigationTitle("Demo App")
        }
    }
}

Why it works: The @State property wraps isolated UI state per Rule 30 in swiftui-ui-patterns/SKILL.md, while NavigationStack follows the architectural pattern documented in the component references.

Example 2: Liquid Glass Background Implementation

When targeting iOS 26+, use the patterns from swiftui-liquid-glass:

import SwiftUI
import LiquidGlass   // Added via SPM per references/liquid-glass.md

struct GlassyProfileView: View {
    var body: some View {
        GlassBackground {
            VStack {
                Text("Profile")
                    .font(.largeTitle)
                    .foregroundColor(.white)
            }
        } // Automatically respects #available(iOS 26, *) checks
    }
}

Key implementation detail: Reference 22 in swiftui-liquid-glass/SKILL.md specifies that GlassBackground handles API-availability guards internally, removing boilerplate from your view code.

Example 3: Running Automated Performance Audits

Invoke the performance skill via Codex CLI to generate profiling reports:

codex run swiftui-performance-audit \
  --target MyApp \
  --device "iPhone 15 Pro" \
  --profile "MainFlow"

This command:

1. Launches Instruments with an ETTrace template
2. Captures a flame-graph processed by optimizing-swiftui-performance helper scripts
3. Generates report-template.md populated with hotspots and refactoring suggestions

(Automation logic detailed in references/optimizing-swiftui-performance.md)

Integrating the Plugin Into Your Workflow

To implement these tools in your own Codex extension:

1. Reference the plugin in your .codex-plugin manifest by cloning the openai/plugins repository or pointing to plugins/build-ios-apps

2. Invoke skills programmatically via the Codex API:

   {
     "plugin": "build-ios-apps",
     "skill": "swiftui-ui-patterns",
     "intent": "Create a new TabView with NavigationStack",
     "params": { "projectName": "MyDemoApp" }
   }

3. Iterate with specialized tools: Use swiftui-view-refactor to decompose large views into stable components, or ios-memgraph-leaks to capture automated memory graph summaries during debug sessions

Summary

• The Build-iOS-Apps plugin provides nine specialized skills for complete SwiftUI development lifecycle management within Codex
• Architecture relies on .codex-plugin/plugin.json for registration and .mcp.json for XcodeBuildMCP integration, with each skill housed in skills/<skill-name>/ containing a SKILL.md and references/ directory
• SwiftUI patterns are governed by the swiftui-ui-patterns skill, which mandates @State for local state and @Observable (iOS 17+) for model objects
• Liquid Glass support requires iOS 26+ and is handled via the swiftui-liquid-glass skill with automatic availability checking
• Performance optimization is automated through swiftui-performance-audit, which generates ETTrace profiles and code-smell reports
• Live previews are available via ios-simulator-browser, which runs a local server for hot-reload SwiftUI previews inside the Codex interface

Frequently Asked Questions

How do I add the Build-iOS-Apps plugin to my existing Codex project?

Clone the openai/plugins repository and reference the plugins/build-ios-apps directory in your .codex-plugin manifest, or invoke skills directly via the Codex API by specifying "plugin": "build-ios-apps" and the target skill name in your JSON payload. Each skill's SKILL.md contains quick-start checklists for integration (see lines 12-18 in swiftui-ui-patterns/SKILL.md).

What is the difference between @State and @Observable in this plugin's patterns?

According to swiftui-ui-patterns/SKILL.md, use @State for narrow, view-local UI state (like toggle switches or text field input), while @Observable (iOS 17+) or ObservableObject (legacy) should wrap external data models that need to propagate changes across multiple views. The skill enforces this separation to prevent performance degradation from over-broadcasting state updates.

Can I use the Liquid Glass skill on older iOS versions?

No. The swiftui-liquid-glass skill explicitly targets iOS 26+ (as documented in Reference 22 of its SKILL.md). The provided GlassBackground wrapper automatically inserts #available(iOS 26, *) checks, ensuring your app compiles for older versions but gracefully falls back to standard backgrounds on unsupported devices.

How does the iOS Simulator Browser enable hot-reload previews?

The ios-simulator-browser skill runs a Node.js script (swiftui-preview-browser.mjs) that compiles your SwiftUI views and serves them over a local web server. This allows the Codex UI to display live previews without launching Xcode, using the template at scripts/templates/PreviewBrowserEntries.swift to bridge SwiftUI previews to the browser environment.

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