---
slug: "pi-build-ios-apps"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/aa2246740/pi-build-ios-apps@main/README.md"
repo: "https://github.com/aa2246740/pi-build-ios-apps"
source_file: "README.md"
branch: "main"
---
# pi-build-ios-apps

[中文](https://github.com/aa2246740/pi-build-ios-apps/blob/HEAD/docs/README.zh-CN.md)

![pi-build-ios-apps hero](https://github.com/aa2246740/pi-build-ios-apps/raw/HEAD/docs/assets/hero.png)

> Browser-first React Native development, with iOS native smoke tests when they matter.

`pi-build-ios-apps` gives the Pi coding agent a fast React Native development
loop first: detect Expo / React Native projects, start a web or Storybook
preview, reuse a cmux browser surface, inspect real browser DOM, and run visual
QA without forcing every UI change through Xcode.

When native proof is actually needed, it still provides the iOS tools: inspect
Xcode, build and launch dev clients on Simulator, read the iOS accessibility
tree, tap/type native elements, and mirror the Simulator through `serve-sim`.

It is designed for visible, local, human-steerable mobile app development.

![real simulator demo](https://github.com/aa2246740/pi-build-ios-apps/raw/HEAD/docs/assets/demo.gif)

## Why This Exists

Coding agents can usually edit an iOS app, but they often stop right before the
part that proves the app actually works: build it, launch it, look at the
Simulator, tap the UI, and report what happened.

`pi-build-ios-apps` closes that gap for Pi.

It gives Pi tools for the fast React Native loop and the slower native evidence
loop:

- Xcode and iOS Simulator environment checks
- React Native / Expo project detection, including Expo Web, Storybook, and `react-native-web`
- browser-first RN preview startup through Expo Web, Storybook, project scripts, or custom commands
- cmux browser reuse, interactive DOM snapshots, selector checks, text/testID checks, and screenshots
- `xcodebuild` scheme listing, build, test, clean, and build-for-testing
- native build/install/launch through the XcodeBuildMCP CLI provider
- native iOS UI snapshots, element refs, wait/assert, tap, type, gesture, and screenshots
- React Native / Expo native dev-client Metro lifecycle support
- `xcrun simctl` boot, install, launch, terminate, screenshot, open URL, privacy, appearance, and content-size controls
- `serve-sim` start, status, stop, tap, type, button, and rotate
- direct browser preview fallback when the official `serve-sim` page is stuck
  on `Connecting`
- clear separation between browser DOM inspection and native iOS UI automation

## Install

From npm:

```sh
pi install npm:pi-build-ios-apps
```

From GitHub:

```sh
pi install git:github.com/aa2246740/pi-build-ios-apps
```

Project-local install:

```sh
pi install -l git:github.com/aa2246740/pi-build-ios-apps
```

From a local checkout:

```sh
pi install /path/to/pi-build-ios-apps
```

Try it once without installing:

```sh
pi -e /path/to/pi-build-ios-apps/extensions/pi-build-ios-apps.ts \
  --skill /path/to/pi-build-ios-apps/skills/pi-build-ios-apps
```

## Quick Start

Inside an iOS project:

```sh
pi
```

Then ask Pi:

```text
/build-ios-app
```

That slash command starts the default React Native-first loop: RN project
detection, web preview startup, cmux browser reuse, DOM/testID checks, visual
QA, and native iOS smoke checks only when native proof is needed.

## Tools

This package registers `/build-ios-app` plus eleven Pi tools:

| Tool | Purpose |
| --- | --- |
| `pi_ios_doctor` | Inspect Xcode, runtimes, Node/npm, CocoaPods, serve-sim, XcodeBuildMCP, and cmux. |
| `pi_ios_xcodebuild` | Run scoped `xcodebuild` actions for projects and workspaces. |
| `pi_ios_build_run` | Build, install, launch, and collect runtime proof through XcodeBuildMCP. |
| `pi_ios_simulator` | Manage Simulator boot, install, launch, terminate, screenshot, URL, privacy, appearance, and content size. |
| `pi_ios_ui` | Read native accessibility snapshots and tap/type/wait/assert elements by refs or selectors. |
| `pi_ios_serve_sim` | Start, stop, inspect, and interact with `serve-sim` for one UDID. |
| `pi_ios_preview` | Start a direct MJPEG pixel-preview page for stuck `Connecting` cases. |
| `pi_ios_react_native` | Detect React Native / Expo native projects and manage Metro for dev builds. |
| `pi_rn_web_preview` | Start or reuse Expo Web, Storybook, project web scripts, or custom RN web previews. |
| `pi_rn_web_verify` | Verify RN web previews through HTTP checks, cmux DOM snapshots, selector/testID/text checks, and screenshots. |
| `pi_ios_cmux_open` | Open or reuse a cmux browser surface for an iOS pixel-preview URL. |

## React Native First

For React Native work, the default path is browser-first:

- `pi_rn_web_preview doctor` detects Expo, React Native, Storybook, web scripts,
  `react-native-web`, package manager, and the recommended browser target.
- `pi_rn_web_preview start` starts Expo Web, Storybook, a project web script, or
  a custom command, then opens/reuses one cmux browser surface.
- `pi_rn_web_verify` checks the URL, asks cmux for an interactive browser DOM
  snapshot, verifies selectors/text/testIDs, and can capture screenshots.

This is the path to use for layout, copy, navigation, visual polish, responsive
states, and most agent self-review. cmux can select the page because it is a
real web page, not a Simulator video stream.

## Native Smoke Gate

Use the iOS path when the change touches native reality:

- HealthKit, permissions, entitlements, native modules, native navigation edges,
  push/deep links, App Store signing, or final acceptance proof.
- `pi_ios_react_native start-metro` keeps a dev client connected to Metro.
- `pi_ios_build_run`, `pi_ios_ui`, `pi_ios_serve_sim`, and `pi_ios_preview`
  provide build/install/launch, native accessibility, and Simulator screenshot evidence.

The Simulator preview is still not browser DOM. In a Simulator mirror, cmux can
select the preview wrapper, usually an image/canvas/MJPEG stream, not native RN
controls. For native element-level work, use `pi_ios_ui` with `testID`,
`accessibilityLabel`, and `accessibilityRole`.

The core loop does not depend on Appium or Detox. Those remain valid external
test stacks for teams that already use them, but this package gives Pi a
browser-first RN loop plus a native smoke gate.

## The Loop

```text
Pi reads the project
  -> pi_ios_react_native doctor detects RN/Expo/native boundaries
  -> pi_rn_web_preview doctor chooses Expo Web, Storybook, script, or custom
  -> pi_rn_web_preview start opens one reusable cmux browser surface
  -> pi_rn_web_verify snapshots real browser DOM and checks selectors/testIDs/text
  -> Pi iterates quickly without Xcode for ordinary UI work
  -> only when needed, pi_ios_build_run + pi_ios_ui run native smoke proof
  -> Pi reports the exact proof boundary
```

## Works Well With pi-company

`pi-build-ios-apps` is a strong companion to
[`pi-company`](https://github.com/aa2246740/pi-company).

`pi-company` turns multiple visible Pi sessions into a local project team:
lead, coder, reviewer, tester, PM, issue ownership, worktrees, and gates.
This package gives that team the missing mobile runtime loop: fast browser QA
for RN work, and slower Simulator proof only when native behavior is at stake.

```text
human -> pi-company lead -> coder worktree -> RN web preview
      -> tester cmux DOM/visual validation -> native smoke gate when needed
      -> review gates -> acceptance -> merge
```

With cmux installed, the whole thing can stay visible: Pi panes on one side,
the RN web preview or Simulator preview on the other, and no hidden cloud
service in the middle.

## React Native, Expo, and HealthKit

For React Native and Expo native projects:

- use `pi_ios_react_native doctor` to identify Expo, React Native, `ios/`
  workspaces/projects, Podfile presence, package manager, and web targets
- use `pi_rn_web_preview doctor/start` as the default UI iteration path
- use `pi_rn_web_verify` for cmux DOM snapshots, selector checks, testID checks,
  text checks, screenshots, and proof-boundary reporting
- keep Metro running before launching a native dev build
- pass launch environment such as `RCT_METRO_PORT` through `pi_ios_simulator`
  when a post-build relaunch is needed
- use `testID` and accessibility props so `pi_ios_ui` can select stable native elements
- expect CocoaPods when the native iOS project or module ecosystem requires it
- do not assume SwiftPM replaces Pods for React Native native modules

SwiftUI support remains available through the iOS tools, but the current product
direction is React Native-first.

## Safety Boundaries

`pi-build-ios-apps` is intentionally local and explicit:

- It does not modify system proxy settings.
- It does not require CocoaPods unless the target project itself requires Pods.
- It scopes `serve-sim` cleanup to one explicit Simulator UDID.
- It defaults cmux preview work toward one reusable browser surface.
- It prefers real RN web DOM for development-stage review.
- It does not claim native iOS controls are selectable browser DOM nodes.
- It uses native accessibility automation for element-level Simulator work.
- It asks Pi to report commands, URLs, simulator IDs, and proof boundaries.

Pi packages can execute local code. Review the source before installing any
third-party package.

## Demo Media and Privacy

The screenshots and GIF in this repository were generated from a synthetic
`FlightDeck` demo app running on a local iOS Simulator. They do not contain real
health data, private source code, API keys, proxy configuration, private Git
remotes, or personal machine paths.

The reproducible SwiftUI demo lives in `examples/FlightDeck`. It is intentionally
small, dependency-free, and built to show the full Pi iOS loop in one first
screen: build status, Simulator runtime proof, browser reuse, agent roles, and
visual QA.

## Requirements

- macOS
- Xcode with an iOS Simulator runtime
- Node.js 20+
- Pi coding agent
- `serve-sim` available through `npx --yes serve-sim@latest`
- `xcodebuildmcp` available through `npx --yes xcodebuildmcp@2.6.2`
- Optional but recommended: cmux

## Development

```sh
npm install
npm run typecheck
npm pack --dry-run
```

Local smoke test:

```sh
pi -e ./extensions/pi-build-ios-apps.ts \
  --skill ./skills/pi-build-ios-apps
```

## Not Affiliated

This is an independent community package. It is not affiliated with Apple,
OpenAI, Codex, Pi, cmux, or the `serve-sim` project unless explicitly stated.

## License

Apache-2.0