Skip to content
New: answer your agents from your phoneLearn more

Run React Native and Expo apps in Git worktrees.

Start one app in two worktrees and both reach for Metro’s port 8081 and the same simulator. Give each worktree its own Metro port and share one development build between them. A worktree that changes native code, or an agent that tests while another does, needs a device of its own.

What clashes when two worktrees run one app

Each worktree is its own checkout, but the worktrees still share your Mac. For a React Native app that means four collisions:

  • Metro's port. Each checkout starts Metro on 8081 by default. The second one fails or moves to another port. If it moves, the app can still load the first worktree's JavaScript, and the agent tests code it didn't write.
  • The installed app. Install the same bundle ID from two worktrees onto one simulator or emulator, and the second install replaces the first.
  • Native folders. Expo's template lists ios/ and android/ in .gitignore, and both Expo's and React Native's list Pods, so a fresh worktree has none of them.
  • Build caches. Xcode names each DerivedData folder after the project's location, so a worktree's first iOS build starts from nothing.

Give each worktree its own Metro port

Expo CLI reads RCT_METRO_PORT from the worktree's .env.local before it picks a port, for expo start and expo run alike. Set a different port in each worktree:

$ echo "RCT_METRO_PORT=8082" >> .env.local
$ npx expo start

Expo treats a port you set this way, or with --port, as fixed. In your terminal, it asks before it moves to another port. It can't ask inside most commands an agent runs, so from SDK 58 it stops there with a PORT_IN_USE error, which tells the agent that another worktree owns the port.

Expo also passes the port it picked to the native builds it starts, and opens a development build with a link that names the port. You don't change anything in Xcode or Gradle.

Without Expo, React Native's CLI takes --port:

$ npx react-native start --port 8082
$ npx react-native run-android --port 8082

react-native start won't move to another port: it stops with an error. run-android writes its port into the Android build. On iOS, React Native 0.84 and later ship the core prebuilt, so a port set at build time may not reach the app. If the app keeps loading the wrong bundle, open the Dev Menu, choose Configure Bundler and enter the worktree's port.

Build the native app once and switch Metro servers

Most tasks touch JavaScript only and need no native build of their own. With Expo's development builds, one build on one simulator can run any worktree's code:

  1. Add expo-dev-client to the project, then build once from your main checkout with npx expo run:ios.
  2. In a worktree, run npx expo start and press i. Expo opens that worktree's Metro server in the app already installed on the simulator.
  3. To check another worktree, press i in its Metro instead. The app switches to that server.

An agent can't press a key in Metro's terminal. From Expo SDK 56, it can send Metro the same request instead:

$ curl -X POST "http://localhost:8082/_expo/open?platform=ios"

A JavaScript-only worktree then needs its node_modules and .env files. It skips the ios/ folder and the Xcode build. Give a worktree its own build only when it changes native code, such as a new native module or a config plugin.

One simulator shows one worktree at a time. If two agents test on it at once, the last one to open the app wins, and the other agent tests the wrong code. Give those worktrees separate devices.

Give a worktree its own simulator or emulator

For iOS, create a simulator named after the worktree and build to it. xcrun simctl list devicetypes lists the device names you can use:

$ xcrun simctl create "fix-login" "iPhone 17"
$ npx expo run:ios --device "fix-login"

With more than one simulator booted, press ShiftI in Metro to choose which one opens the app. An agent can ask its Metro for the development build's link, then open the url from the reply on its own simulator. xcrun simctl list devices shows each simulator's UDID:

$ curl -s "http://localhost:8082/_expo/open?platform=ios"
$ xcrun simctl openurl <udid> "<url>"

If a second expo run:ios --device takes over the other worktree's simulator, update Expo CLI. Expo fixed that bug in version 55.0.19.

For Android, create a second virtual device in Android Studio's Device Manager and start it. adb gives each running emulator its own serial, and Expo builds to the one you name:

$ adb devices
List of devices attached
emulator-5554	device
emulator-5556	device
$ npx expo run:android --device emulator-5556

Expo runs adb reverse for the worktree's port on every connected emulator as it opens the app, so the emulator reaches that worktree's Metro.

To keep two worktrees' builds on one device, give them different bundle IDs. Expo's app variants guide shows how to set ios.bundleIdentifier and android.package from an environment variable in app.config.js. Set scheme from it too, or both builds answer the same development link. Put the variable in each worktree's .env.local, where Expo's commands read it. If Expo generates your native folders, run npx expo prebuild --clean after you change it, since expo run builds the native folders it finds.

Expo's experimental agent CLI can also give each worktree its own simulator or emulator.

Fill in what a fresh worktree is missing

  • node_modules: clone or install it, don't symlink it. Metro follows a symlink only to a target inside the project root or its watchFolders, and Expo sets no watchFolders outside a monorepo. Setting up a worktree for an agent covers cloning it copy-on-write.
  • .env files. In development, Expo loads .env.development.local, .env.local, .env.development and .env. Its template ignores the .local files, so copy those into each worktree.
  • Native folders and Pods. npx expo run:ios generates a missing ios/ folder and installs Pods. React Native's run-ios installs missing Pods too.
  • Android build cache. Gradle's build cache is off by default. Turn it on and Gradle reuses cacheable task outputs whose inputs match, from builds in any folder on your Mac, so a worktree's first Android build has less to do:
$ echo "org.gradle.caching=true" >> ~/.gradle/gradle.properties

Keep worktrees outside the project folder. Metro watches the files under the project root, so a worktree nested inside it shows Metro a second copy of the app, which can cause duplicate-module errors. If yours have to live there, add their folder to resolver.blockList in metro.config.js.

Leave Metro's cache alone

Metro keeps one transform cache that all your projects share, in $TMPDIR/metro-cache. It keys each entry by the file's contents, its path in the project and Metro's settings, so worktrees of one project share entries without mixing them up. npx expo start --clear and --reset-cache empty the whole store, and each worktree starts cold the next time its Metro starts.

If the app shows old code, check the port before you clear anything. An app loading another worktree's Metro shows old code too.

Tell the agent which port and device are its own

An agent doesn't know which port and device belong to its worktree, or that clearing Metro's cache affects the others. Add the rules to the project's AGENTS.md:

## Metro
- Start Metro with `npx expo start`. It reads this worktree's port from .env.local.
- If that port is taken, stop and tell me. Don't pick another port.
- Don't use --clear or --reset-cache unless I ask.
  Metro shares one cache across worktrees.
- Don't set CI=1 or CI=true. Metro stops watching files in CI mode,
  so the app won't reload.
- Take screenshots of your own simulator by its UDID, not "booted".

With several simulators booted, booted may not be the one the agent means. These commands take a screenshot of one device by UDID or serial:

$ xcrun simctl io <udid> screenshot screen.png
$ adb -s emulator-5556 exec-out screencap -p > screen.png

Watch the app and send screenshots in ket

ket clones node_modules copy-on-write and copies .env.local and .env.*.local into each worktree it provisions. The copied .env.local holds your main checkout's port, so change RCT_METRO_PORT in each new worktree. ket worktree add provisions every worktree it creates; for a worktree made in the app, run Re-run provisioning for a worktree from the command palette.

The + on a worktree's tab bar opens an iOS Simulator tab or an Android Emulator tab beside the agent:

  • The iOS Simulator tab shows the booted iPhone or iPad you used most recently, or starts one from a list. It needs Apple silicon and Xcode.
  • The Android tab shows the newest running emulator, or starts one of your virtual devices. It needs the Android SDK.

ket keeps one of each open at a time, in the worktree you opened it from. While the iOS Simulator tab is open, ket hides Apple's Simulator app each time it launches, so the same phone doesn't show in two windows. Bring Simulator back from the Dock to watch a second device.

Press ⌘S in either tab, and ket opens Screenshot to agent with the screenshot attached, addressed to the tab's worktree. If the device is running another worktree's Metro, pick that worktree from the target menu before you send. Type or dictate what's wrong, and press ⌘S again to add another screenshot. To fix it apart from the task in progress, send it to a new worktree.

ket doesn't assign Metro ports or create simulators. The steps above do that.