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

> Learn to implement SwiftUI apps seamlessly using the Build-iOS-Apps plugin. This comprehensive Codex guide covers everything from view scaffolding to performance profiling.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: how-to-guide
- Published: 2026-07-02

---

**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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json), which declares the plugin name, version (`0.1.1`), and skill directory location. Complementing this is [`.mcp.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/SKILL.md) at [`skills/swiftui-liquid-glass/SKILL.md`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/profiling-intake.md): Instructions for attaching Instruments
- [`report-template.md`](https://github.com/openai/plugins/blob/main/report-template.md): Auto-populated audit results
- [`code-smells.md`](https://github.com/openai/plugins/blob/main/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:

```swift
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`](https://github.com/openai/plugins/blob/main/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`:

```swift
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`](https://github.com/openai/plugins/blob/main/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:

```bash
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`](https://github.com/openai/plugins/blob/main/report-template.md) populated with hotspots and refactoring suggestions

*(Automation logic detailed in [`references/optimizing-swiftui-performance.md`](https://github.com/openai/plugins/blob/main/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:

   ```json
   {
     "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`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) for registration and [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) for XcodeBuildMCP integration, with each skill housed in `skills/<skill-name>/` containing a [`SKILL.md`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/SKILL.md) contains quick-start checklists for integration (see lines 12-18 in [`swiftui-ui-patterns/SKILL.md`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/scripts/templates/PreviewBrowserEntries.swift) to bridge SwiftUI previews to the browser environment.