# Native iOS and Android Recipes

URL: https://developertoolkit.ai/en/cookbook/mobile-development/native-ios-android/
Description: Swift/SwiftUI and Kotlin/Compose with an agent: one build-and-test script per platform, simulator and emulator loops, fast builds, and UI-test evidence.

Native iOS and Android development with a coding agent works when each platform has one script that builds the app, runs its tests on a pinned simulator or emulator, and saves the results as evidence. Claude Code, Codex, and Cursor iterate against that script, and an MCP server such as MobileBuildMCP or mobile-mcp lets the agent see the running app.

You ask the agent for a new SwiftUI settings screen. It writes clean Swift, announces "done", and the project does not build, because the new file never reached the Xcode target. On the Android side, the agent runs `./gradlew clean build` on every change, waits minutes for a result, and pastes thousands of lines of Gradle output into its own context. Neither agent ever looked at the screen it built. This page fixes those three gaps: build feedback, speed, and proof.

## What you get from an agent-ready native project

- Two copy-paste scripts, `scripts/ios-check.sh` and `scripts/android-check.sh`. Each one boots a pinned device, runs the tests, writes a short summary for the agent, and saves the full evidence under `build/evidence/`.
- An instructions block for `AGENTS.md`, `CLAUDE.md`, or a Cursor rule that makes "the script exits 0" the definition of done.
- Verified install commands for the two mobile MCP servers, plus the Codex plugins for iOS and Android, per tool.
- Build-time rules that keep the agent's inner loop short: narrow test selection, warm devices, and caches.
- Recipes for a SwiftUI screen, a Jetpack Compose screen, and a crash reproduction, each ending in UI-test evidence rather than a diff you have to read.

## Why native apps need a different agent loop

Web agents get cheap feedback: a dev server reloads in a second and a browser MCP shows the page. Native projects take longer to give that feedback, for three reasons:

1. **The project file is part of the build.** Xcode decides what compiles from the target membership in `project.pbxproj`, and Gradle from the module layout. An agent that writes a correct file in the wrong place gets a build error or, worse, a file that silently never compiles.
2. **Builds are slow and loud.** A clean `xcodebuild` or Gradle build prints thousands of lines. Streamed into the agent's context, that output costs tokens and pushes the task instructions out of view.
3. **The UI lives in a separate process.** The simulator and the emulator are separate programs. Without a test runner or an MCP server, the agent has no way to know whether the screen renders, and neither do you.

So the recipes on this page do not start with a feature prompt. They start by giving the agent a single, quiet, reliable command per platform, and they judge the agent by what that command proves.

## Set up the build-and-verify loop

1. **Pin one simulator and one emulator.** List what exists with `xcrun simctl list devices available` and `emulator -list-avds` (the `emulator` binary lives in `$ANDROID_HOME/emulator`). Pick one of each and write the names into the scripts below. A pinned device means a test failure is about your code, not about which phone the agent happened to boot.

2. **Add `scripts/ios-check.sh`.** It keeps DerivedData inside the repository, writes the full log to a file, and prints only the lines the agent needs:

   ```bash
   #!/usr/bin/env bash
   # scripts/ios-check.sh — build, test and collect evidence on one pinned simulator.
   # Usage: scripts/ios-check.sh [TestTarget/TestClass ...]   (no argument = all tests)
   set -euo pipefail
   SCHEME="${SCHEME:-App}"
   SIM="${SIM:-iPhone 17}"
   OUT="build/evidence/ios"
   rm -rf "$OUT" && mkdir -p "$OUT"

   ONLY=()
   for t in "$@"; do ONLY+=("-only-testing:$t"); done

   xcrun simctl bootstatus "$SIM" -b >/dev/null   # boots the simulator if needed, waits until ready

   set +e
   xcodebuild test \
     -scheme "$SCHEME" \
     -destination "platform=iOS Simulator,name=$SIM" \
     -derivedDataPath build/DerivedData \
     -resultBundlePath "$OUT/tests.xcresult" \
     ${ONLY[@]+"${ONLY[@]}"} > "$OUT/xcodebuild.log" 2>&1
   STATUS=$?
   set -e

   xcrun xcresulttool get test-results summary --path "$OUT/tests.xcresult" > "$OUT/summary.json" 2>/dev/null || true
   grep -E "error:|\*\* (BUILD|TEST) (SUCCEEDED|FAILED)|failed" "$OUT/xcodebuild.log" | tail -40
   echo "exit=$STATUS evidence=$OUT"
   exit $STATUS
   ```

   The `${ONLY[@]+...}` form matters: macOS still ships Bash 3.2, where an empty array under `set -u` aborts the script. `xcresulttool get test-results` needs Xcode 16 or later.

3. **Add `scripts/android-check.sh`.** It reuses a running emulator, clears logcat so the log covers only this run, and copies the Gradle test reports into the evidence folder:

   ```bash
   #!/usr/bin/env bash
   # scripts/android-check.sh — unit + instrumented tests on one pinned emulator, evidence collected.
   # Usage: scripts/android-check.sh [com.example.app.SomeUiTest]   (no argument = all tests)
   set -euo pipefail
   AVD="${AVD:-Pixel_8_API_35}"
   MODULE="${MODULE:-app}"
   OUT="build/evidence/android"
   rm -rf "$OUT" && mkdir -p "$OUT"

   if ! adb get-state >/dev/null 2>&1; then
     emulator -avd "$AVD" -no-window -no-audio -no-boot-anim > "$OUT/emulator.log" 2>&1 &
     adb wait-for-device
     until [ "$(adb shell getprop sys.boot_completed | tr -d '\r')" = "1" ]; do sleep 2; done
   fi
   adb logcat -c

   FILTER=()
   if [ $# -gt 0 ]; then FILTER=("-Pandroid.testInstrumentationRunnerArguments.class=$1"); fi

   set +e
   ./gradlew ":$MODULE:testDebugUnitTest" ":$MODULE:connectedDebugAndroidTest" \
     ${FILTER[@]+"${FILTER[@]}"} > "$OUT/gradle.log" 2>&1
   STATUS=$?
   set -e

   adb logcat -d > "$OUT/logcat.txt"
   cp -R "$MODULE/build/reports" "$OUT/reports" 2>/dev/null || true
   cp -R "$MODULE/build/outputs/androidTest-results" "$OUT/androidTest-results" 2>/dev/null || true
   grep -E "FAILED|BUILD (SUCCESSFUL|FAILED)|e: " "$OUT/gradle.log" | tail -40
   echo "exit=$STATUS evidence=$OUT"
   exit $STATUS
   ```

   The optional argument narrows only the instrumented run to one class; unit tests always run in full, because they are cheap.

4. **Tell the agent the rules.** Paste this block into `AGENTS.md` for Codex, `CLAUDE.md` for Claude Code, or a project rule for Cursor. Claude Code reads `AGENTS.md` when the repository has no `CLAUDE.md` (v2.1.277 or later, both release channels on 2026-10-12), so one file can serve both CLIs. If you have not written an instructions file before, start with [AGENTS.md and CLAUDE.md](/en/developer-scorecard-guide/claude-md-context/):

   ```markdown
   ## Native build and test loop
   - iOS: run `scripts/ios-check.sh`, optionally with a test class such as `AppUITests/SettingsUITests`.
     Never call `xcodebuild` without `-derivedDataPath build/DerivedData`.
   - Android: run `scripts/android-check.sh`, optionally with a fully qualified test class.
     Never run `./gradlew clean` unless the user asks.
   - A task is done only when the relevant script prints `exit=0`. Quote its summary lines in your final message.
   - Every control a test touches gets a stable ID: `.accessibilityIdentifier(...)` in SwiftUI,
     `Modifier.testTag(...)` in Compose. Never locate elements by visible text alone.
   - Never edit snapshot references (`__Snapshots__/`, `src/test/snapshots/`) or weaken an existing
     assertion to make a test pass. Stop and report the failure instead.
   - New Swift files go inside an existing synchronized folder; do not edit `project.pbxproj` by hand.
   ```

5. **Commit the scripts and run them once yourself.** A script that fails on a clean checkout teaches the agent to ignore it. Run both, open `build/evidence/`, and add `build/` to `.gitignore` if it is not there yet.

**Why the scripts hide most of the output**

The full log is still on disk in `build/evidence/`. The agent sees about 40 lines: the errors and the pass or fail verdict. When it needs more, it can `grep` the log itself. That keeps a slow build from eating the context window that should hold your spec.

## Connect the agent to the simulator and emulator

Tests prove the behaviour you wrote down. For exploratory work (does the screen look right, what happens when I tap here), the agent needs to see and drive the device. Two MCP servers cover this. If you have never added an MCP server, read the [introduction to MCP](/en/ecosystem/mcp/) first:

- **MobileBuildMCP** (formerly XcodeBuildMCP, maintained by Sentry) builds, runs, and debugs iOS and macOS projects on simulators and devices. It needs macOS 14.5+ and Xcode 16+. Its most-used tool is `build_run_sim`, which builds the scheme, installs the app on a booted simulator, launches it, and captures logs.
- **mobile-mcp** (Mobile Next) drives iOS simulators, Android emulators, and real devices through one tool set: `mobile_list_elements_on_screen` for an accessibility snapshot, `mobile_take_screenshot`, `mobile_click_on_screen_at_coordinates`, `mobile_get_device_logs`, `mobile_get_crash`, and more. Version 1.0.5 advertises 32 tools.

Popularity: on 2026-09-26 MobileBuildMCP had 6.4k GitHub stars and npm `mobilebuildmcp` 2.7.1 (published 2026-09-23); on 2026-09-28 mobile-mcp had 7,958 GitHub stars, with npm `@mobilenext/mobile-mcp` 1.0.5 (published 2026-09-23). Sources: the GitHub repositories `getsentry/MobileBuildMCP` and `mobile-next/mobile-mcp`, and the npm registry.

**Claude Code**

    Add the servers from the terminal. The default `local` scope keeps them out of teammates' sessions until you decide to share them with `-s project`:

    ```bash
    claude mcp add mobilebuild -- npx -y mobilebuildmcp@latest mcp
    claude mcp add mobile-mcp -- npx -y @mobilenext/mobile-mcp@latest
    ```

    The Claude Code desktop app on macOS also has an iOS Simulator pane (beta since July 2026), so you can watch the simulator next to the session. To keep the agent away from snapshot references, add deny rules to `.claude/settings.json`:

    ```json
    {
      "permissions": {
        "deny": [
          "Edit(**/__Snapshots__/**)",
          "Edit(**/src/test/snapshots/**)"
        ]
      }
    }
    ```

**Codex**

    Add the servers with `codex mcp add` (the `--` separates the server command):

    ```bash
    codex mcp add mobilebuild -- npx -y mobilebuildmcp@latest mcp
    codex mcp add mobile-mcp -- npx -y @mobilenext/mobile-mcp@latest
    ```

    Simulator builds can outlast the default MCP tool timeout. MobileBuildMCP's client docs tell Codex users to raise it per server in `~/.codex/config.toml`, because Codex ignores a top-level `tool_timeout_sec` for MCP calls:

    ```toml
    [mcp_servers.mobilebuild]
    command = "npx"
    args = ["-y", "mobilebuildmcp@2.7.1", "mcp"]   # pinned, like the committed configs
    tool_timeout_sec = 600
    ```

    Codex's official plugin marketplace also lists `build-ios-apps` (skills such as `ios-debugger-agent`, `swiftui-ui-patterns`, and `swiftui-performance-audit`, with an XcodeBuildMCP configuration) and `test-android-apps` (skills `android-emulator-qa` and `android-performance`); checked in `openai/plugins` on 2026-09-26. Install them from the TUI: run `/plugins` and search by name.

    Two details from the plugin files (version 0.1.2 of each): `build-ios-apps` starts the server under its old package name, `xcodebuildmcp@latest`, with four workflows switched on (`simulator,ui-automation,debugging,logging`), and it can mirror the simulator in the Codex in-app browser. If you also added `mobilebuild` by hand, disable one of the two, or the agent sees every build tool twice.

**Cursor**

    Add a project-scoped `.cursor/mcp.json` so every teammate who opens the repository gets the same servers:

    ```json
    {
      "mcpServers": {
        "mobilebuild": {
          "command": "npx",
          "args": ["-y", "mobilebuildmcp@2.7.1", "mcp"]
        },
        "mobile-mcp": {
          "command": "npx",
          "args": ["-y", "@mobilenext/mobile-mcp@1.0.5"]
        }
      }
    }
    ```

    The versions are pinned because this file is committed: with `@latest`, every teammate's next session silently runs whatever was published overnight. Bump the pins in a pull request, like any other dependency.

    Cursor's agent runs `scripts/ios-check.sh` and `scripts/android-check.sh` in its terminal like any other command. For Cursor-specific mobile tips, see [Cursor mobile development](/en/cursor-ide/build/mobile-dev/).

**Before you connect a device server**

Both servers send telemetry by default: set `MOBILEBUILDMCP_SENTRY_DISABLED=true` for MobileBuildMCP (the old `xcodebuildmcp` package, which Codex's `build-ios-apps` plugin still launches, reads `XCODEBUILDMCP_SENTRY_DISABLED`) and `MOBILEMCP_DISABLE_TELEMETRY=1` for mobile-mcp if your policy requires it. mobile-mcp can also drive a real, USB-connected phone, which means the agent can read whatever is on that screen. Use a test device with test accounts, never your personal phone. MobileBuildMCP's device tools also need code signing configured in Xcode.

**When to use which.** Use MobileBuildMCP when the problem is the Xcode build itself (schemes, signing, a Swift macro, a crash on launch). Use mobile-mcp when the problem is behaviour on screen, on either platform. Enable only the server a session needs: every advertised tool definition takes context on every turn. mobile-mcp 1.0.5 advertises all 32 tools at once. MobileBuildMCP exposes only its `simulator` workflow by default; widen it with the `MOBILEBUILDMCP_ENABLED_WORKFLOWS` environment variable (for example `simulator,ui-automation,debugging,logging`) only when the task needs UI automation or the debugger. In Claude Code that is `claude mcp add mobilebuild -e MOBILEBUILDMCP_ENABLED_WORKFLOWS=simulator,ui-automation -- npx -y mobilebuildmcp@latest mcp`. Codex's `build-ios-apps` plugin sets `XCODEBUILDMCP_ENABLED_WORKFLOWS` instead only because it runs the old `xcodebuildmcp@latest` package; `mobilebuildmcp` 2.7.1 ignores that name.

**Working inside Xcode instead of a terminal.** MobileBuildMCP's client documentation (checked 2026-09-26) describes Xcode 26.3 or later hosting the Codex and Claude Code agents under **Xcode Settings > Intelligence**. Those in-Xcode agents start with a minimal `PATH`, so a server launched with `npx` often fails to start; the documentation wraps the command in `/bin/zsh -lc` with Homebrew and nvm on the `PATH`. The check scripts on this page work the same from either place.

## How to keep native build times inside the agent's loop

A slow loop changes agent behaviour: the agent batches many edits between builds, and a failure then has many possible causes. Keep three loops, each with its own cost:

| Loop | What runs | Command | When the agent runs it |
| --- | --- | --- | --- |
| Inner | Unit tests of the changed module (Swift Testing or XCTest; JUnit) | `xcodebuild test ... -only-testing:AppTests/CartTests` · `./gradlew :feature:cart:testDebugUnitTest --tests '*CartViewModelTest'` | After every edit |
| Middle | One UI test class on the pinned device | `scripts/ios-check.sh AppUITests/CartUITests` · `scripts/android-check.sh com.example.cart.CartScreenTest` | Before it claims "done" |
| Outer | Every suite, snapshot verification, both platforms | The same two scripts without arguments, in CI | On every pull request |

Rules that keep the inner and middle loops fast:

- **Never clean by reflex.** Tell the agent in its instructions file that `clean` is forbidden unless you ask. Most "fix it with a clean build" instincts come from stale DerivedData or Gradle caches, and the failure list below has the targeted fix for them.
- **Keep devices warm.** Both scripts boot the device only when it is not running. Leave the simulator and the emulator up for the whole session.
- **Turn on Gradle's caches.** Add `org.gradle.caching=true` and `org.gradle.configuration-cache=true` to `gradle.properties`. The configuration cache skips re-running build scripts when nothing in them changed.
- **Split build from test on iOS when you rerun.** `xcodebuild build-for-testing` followed by `xcodebuild test-without-building` reruns a flaky test without recompiling. Use it for triage only: after a code change the agent must rebuild.
- **Measure before tuning.** `xcodebuild -showBuildTimingSummary` prints where the time went, and `./gradlew --profile` writes a local HTML report under `build/reports/profile/`. Ask the agent to read the report and propose one change, then measure again.

**Copy-paste prompt: find the slowest part of the build**

```text
Run `./gradlew :app:assembleDebug --profile` twice (the second run shows the incremental cost),
then read the newest report under build/reports/profile/. List the five slowest tasks with their
durations, explain why each one runs on an incremental build, and propose ONE change to
gradle.properties or a build script that removes the biggest cost. Do not apply it yet. Show me
the change and the command you will use to prove it helped.
```

## Recipe: a SwiftUI screen with UI-test evidence

The prompt below asks for the behaviour first, as tests, and makes the script's exit code the finish line.

**Copy-paste prompt: SwiftUI settings screen with proof**

```text
Build a SwiftUI SettingsView with a "Daily reminder" Toggle and a DatePicker that is only enabled
when the toggle is on. The state lives in an @Observable SettingsModel persisted to UserDefaults.

Work in this order:
1. Write Swift Testing tests (import Testing, @Test, #expect) for SettingsModel: default is off,
   toggling persists, the time survives a relaunch (new model instance reading the same defaults suite).
2. Write an XCUITest class AppUITests/SettingsUITests that launches the app with the launch argument
   "-uiTesting", opens Settings, turns the toggle on, and asserts the DatePicker is enabled.
   Attach a screenshot after each step with XCTAttachment and lifetime .keepAlways.
3. Implement until `scripts/ios-check.sh AppUITests/SettingsUITests` prints exit=0, then run
   `scripts/ios-check.sh` with no argument.
Put new files in the existing synchronized folders. Give every control an accessibilityIdentifier.
Finish with the script's summary lines and the list of tests you added.
```

The screenshots land inside `build/evidence/ios/tests.xcresult`, next to the test that took them. The attachment code the agent should produce looks like this:

```swift
let app = XCUIApplication()

func snap(_ name: String) {
    let shot = XCTAttachment(screenshot: app.screenshot())
    shot.name = name
    shot.lifetime = .keepAlways   // keep it even when the test passes
    add(shot)
}

func testEnablingReminderEnablesTimePicker() {
    app.launchArguments = ["-uiTesting"]
    app.launch()
    app.buttons["settings.open"].tap()
    snap("1-settings-open")
    app.switches["settings.reminderToggle"].tap()
    snap("2-reminder-on")
    XCTAssertTrue(app.datePickers["settings.reminderTime"].isEnabled)
    snap("3-time-picker-enabled")
}
```

Check one thing the agent often gets wrong: the `-uiTesting` launch argument has to change app behaviour (an in-memory `UserDefaults` suite, no onboarding). If nothing in the app reads it, the UI test depends on whatever state the last run left behind and will flake.

## Recipe: a Jetpack Compose screen with UI-test evidence

**Copy-paste prompt: Compose cart screen with proof**

```text
Build a Jetpack Compose CartScreen backed by a CartViewModel (StateFlow<CartUiState>) with three
states: Loading, Empty, and Items(list, total). Quantity steppers update the total immediately.

Work in this order:
1. JUnit tests for CartViewModel with a fake repository: empty cart gives Empty, incrementing a line
   updates the total, a repository error gives an error state with a retry action.
2. A Compose UI test com.example.cart.CartScreenTest using createAndroidComposeRule<MainActivity>():
   find nodes by Modifier.testTag, tap "+" on the first line, assert the total text changes.
3. Implement until `scripts/android-check.sh com.example.cart.CartScreenTest` prints exit=0,
   then run `scripts/android-check.sh` with no argument.
Do not run ./gradlew clean. Finish with the script's summary lines and the tests you added.
```

A correct Compose test finds nodes by tag, not by text, so a copy change does not break it:

```kotlin
@get:Rule val composeRule = createAndroidComposeRule<MainActivity>()

@Test
fun incrementUpdatesTotal() {
    composeRule.onNodeWithTag("cart.line.0.increment").performClick()
    composeRule.onNodeWithTag("cart.total").assertTextEquals("Total: 24.00")
}
```

For visual evidence on Android without an emulator, add a screenshot-test library such as Paparazzi: `./gradlew :app:recordPaparazziDebug` records reference images, and `./gradlew :app:verifyPaparazziDebug` fails when the rendering changes. On iOS, `swift-snapshot-testing` plays the same role with `assertSnapshot(of: view, as: .image)`. Both record references on the first run, so review and commit those references yourself.

## Recipe: reproduce a crash the agent cannot see

A crash report with a stack trace is a spec for a failing test. Hand it over with the device server connected:

**Copy-paste prompt: turn a crash into a failing test**

```text
Here is a crash from our Android beta (stack trace below). Using the mobile-mcp tools:
1. Launch the debug build on the running emulator, follow the steps in the report, and capture
   mobile_get_device_logs and a screenshot when it crashes.
2. Write the smallest instrumented or unit test that reproduces the crash. Run it with
   scripts/android-check.sh and show me it FAILS for the same reason as the report.
3. Only then fix the code, rerun the script until exit=0, and explain the root cause in two sentences.
Do not change or delete any existing test.

<paste the stack trace here>
```

The order matters. A test that failed before the fix and passes after it is evidence. A fix with no failing test first is a guess that happened to compile.

## How to verify the agent's native work without reading every line

The scripts turn every change into the same bundle of artifacts, and review starts from that bundle, not from the diff:

| Evidence | Where it lives | What a reviewer checks |
| --- | --- | --- |
| Test verdict | Last lines of the script output, `summary.json`, JUnit XML under `androidTest-results/` | `exit=0` on both platforms; the count of tests went up, never down |
| UI screenshots | `tests.xcresult` attachments (open in Xcode), Paparazzi or snapshot-testing images | The screens match the spec; snapshot diffs are intentional |
| Runtime logs | `xcodebuild.log`, `logcat.txt` | No new crashes, ANRs, or error spam during the UI tests |
| Test changes | The test files in the diff | New tests assert the acceptance criteria; no assertion was weakened, no snapshot re-recorded without a reason |

Three rules make this trustworthy:

1. **CI runs the same scripts.** A green result in the agent's session is a claim; the same script in CI on a clean macOS runner is the proof. Keep the scripts in the repository so the two cannot drift.
2. **The agent cannot edit the oracle.** Snapshot references and the tests that encode the acceptance criteria are protected, as described in [protecting the oracle](/en/workflows/test/protect-the-oracle/). Claude Code gets per-path deny rules (the Claude Code tab above). For Codex and Cursor this page relies on a tool-neutral guard instead, and it backs up Claude Code too: CODEOWNERS on the reference folders, plus a CI step that fails when they change without a label.

   ```text
   # .github/CODEOWNERS
   **/__Snapshots__/        @your-org/mobile-leads
   **/src/test/snapshots/   @your-org/mobile-leads
   ```

   ```yaml
   # CI job step (check out with fetch-depth: 0 so origin/main is available)
   - name: Block unlabelled snapshot changes
     if: ${{ !contains(github.event.pull_request.labels.*.name, 'snapshot-update') }}
     run: |
       if git diff --name-only origin/main... | grep -E '__Snapshots__/|src/test/snapshots/'; then
         echo "Snapshot references changed without the snapshot-update label"; exit 1
       fi
   ```
3. **A named person signs off on the evidence.** The developer who assigned the task reviews the evidence bundle and the test diff. The code diff gets a full human read only where risk requires it: signing, entitlements, payments, and anything touching `Info.plist` permissions or `AndroidManifest.xml`.

The pull-request contract for this bundle is described in [the evidence bundle](/en/workflows/ship/evidence-bundle/), and the reasoning for reviewing evidence instead of diffs in [reading evidence instead of code](/en/ladder/evidence-not-diffs/).

## When native agent loops break

**Common failures and how to recover**

**The new Swift file compiles in the editor but not in the build.** The file is outside every target. Convert the group to a synchronized folder in Xcode 16 or later (right-click the group, **Convert to Folder**) so any file placed inside it joins the target, then tell the agent where new files go. Do not let it hand-edit `project.pbxproj`; a merge conflict there is expensive to untangle.

**"Unable to find a destination matching the provided destination specifier."** The pinned simulator name does not exist in this Xcode version. Run `xcrun simctl list devices available`, update `SIM` in the script, and commit it. Do not let the agent pick "any iPhone" on its own; that unpins the device.

**Builds fail inside the sandbox with permission errors.** Xcode writes to `~/Library/Developer/Xcode/DerivedData` by default, which is outside the project. The scripts pass `-derivedDataPath build/DerivedData` for exactly this reason; check that the agent is not calling `xcodebuild` directly.

**The emulator never finishes booting in CI.** Headless runners often lack hardware acceleration. Check the emulator log in `build/evidence/android/emulator.log`, and use a runner with KVM enabled or Gradle Managed Devices instead of a hand-started emulator.

**The agent re-records snapshots to make a test pass.** Setting `record: .all` in swift-snapshot-testing or running `recordPaparazziDebug` turns every visual regression green. Deny edits to the reference folders, and treat any changed reference image in a pull request as a change that needs a reason.

**The build fails with stale module or cache errors.** Errors such as a module compiled with a different compiler, a missing precompiled header, or a Gradle configuration-cache mismatch come from caches, not from your code. On iOS, delete only `build/DerivedData/ModuleCache.noindex` (or `build/DerivedData` as a whole, which the scripts own). On Android, run `./gradlew --stop` and remove `.gradle/configuration-cache`. Then rerun the check script. Do not run a full `clean`: it throws away every warm cache and makes the next few agent iterations slow.

**A teammate's MCP server behaves differently from yours.** Someone's session pulled a newer `@latest` release overnight. Pin the server version in every committed config (`.cursor/mcp.json`, or the `.mcp.json` that `claude mcp add -s project` writes), use the same pinned version in `~/.codex/config.toml`, and upgrade it deliberately.

**MCP calls time out during a build.** In Codex, set `tool_timeout_sec` inside the server's own `[mcp_servers.<name>]` block. In any tool, prefer the check script for the full build and use the MCP server for launching and inspecting the app.

**The context fills with build output.** The agent is running `xcodebuild` or `./gradlew` directly instead of the scripts. Point it back to the rule in its instructions file and ask it to `grep` the saved log for the error it needs.

## Model and effort for native work

Start on your tool's default model and raise effort before you switch model; current defaults and prices are on the [models hub](/en/ecosystem/models/). Native tasks are more often limited by build feedback than by the model, so fix the loop first.

## Where to go next with native iOS and Android agents

- [Mobile app testing patterns](/en/workflows/test/mobile-testing/) — Device matrices, Detox and Maestro flows, and gesture and offline tests across platforms.
- [The evidence bundle](/en/workflows/ship/evidence-bundle/) — The pull request contract that turns the scripts' output into a reviewable proof.
- [Framework dev-tools MCP servers](/en/ecosystem/mcp/framework-devtools-mcp/) — MobileBuildMCP next to the other servers that put a running app in the agent's loop.
- [React Native patterns](/en/cookbook/mobile-development/react-native/) — The cross-platform alternative, with Expo, FlashList, and EAS Build.
- [Flutter patterns](/en/cookbook/mobile-development/flutter/) — Riverpod, go_router, and widget tests when one Dart codebase serves both platforms.
- [Mobile development overview](/en/cookbook/mobile-development/) — All mobile recipes, and which stack each one fits.
