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/andandroid/in.gitignore, and both Expo's and React Native's listPods, 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 startExpo 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 8082react-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:
- Add
expo-dev-clientto the project, then build once from your main checkout withnpx expo run:ios. - In a worktree, run
npx expo startand press i. Expo opens that worktree's Metro server in the app already installed on the simulator. - 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-5556Expo 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 itswatchFolders, and Expo sets nowatchFoldersoutside a monorepo. Setting up a worktree for an agent covers cloning it copy-on-write..envfiles. In development, Expo loads.env.development.local,.env.local,.env.developmentand.env. Its template ignores the.localfiles, so copy those into each worktree.- Native folders and Pods.
npx expo run:iosgenerates a missingios/folder and installs Pods. React Native'srun-iosinstalls 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.propertiesKeep 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.pngWatch 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.
Related guides
Test an Android app with a coding agent.
Use an Android emulator beside Codex, send screenshot feedback with ⌘S, and capture screens with adb.
Set up a Git worktree for a coding agent.
Dependencies, .env files, ports and databases: what a fresh worktree is missing and how to fill it in.
Test a local web app with a coding agent.
Let an agent open your dev server in a Chromium tab, click through the change, read the console and record what it did.
Run coding agents in parallel without sharing a working directory.
How to split work between agents, watch them, and merge the results one at a time, smallest dependency first.