pi-build-ios-apps

中文

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.

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:

pi install npm:pi-build-ios-apps

From GitHub:

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

Project-local install:

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

From a local checkout:

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

Try it once without installing:

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:

pi

Then ask Pi:

/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

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.

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.

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 [email protected]
• Optional but recommended: cmux

Development

npm install
npm run typecheck
npm pack --dry-run

Local smoke test:

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