6 min read
Worktrees for iOS coding agents: parallel builds without simulator collisions
How to isolate iOS coding-agent work with Git worktrees, per-branch simulators, derived-data paths, and build rules that prevent parallel sessions from corrupting each other.
On this page7
Running two coding agents on one iOS repo usually goes fine for about ten minutes. Then one agent switches branches under the other, or both install the same bundle ID on the same booted simulator, and the second agent spends twenty minutes debugging a failure the first one caused.
Git worktrees fix the source half of that problem. The Xcode half needs its own rules, because the simulator, build products, and package caches live outside the repository and Git knows nothing about them.
This post covers the setup I use when more than one agent works on an iOS app at the same time. It assumes you already have the basics from AGENTS.md for iOS and prompting coding agents for iOS work.
1. One agent, one worktree, one branch
A worktree is a second checkout of the same repository in a different directory, sharing one object database. Each agent gets its own:
git fetch origin
git worktree add -b agent/smart-import ../packerly-agent-1 origin/main
git worktree add -b agent/paywall-copy ../packerly-agent-2 origin/mainGit refuses to check out the same branch in two worktrees, which is exactly the guard you want. Two agents can no longer edit the same branch or run git checkout in a directory someone else is building from.
Keep the main checkout for yourself. Agents work in their slots, and you review and merge from a tree nobody else is touching.
If the project uses XcodeGen or Tuist, the generated project is per worktree too. Regenerate it after creating the worktree and after every change to the manifest. A stale .xcodeproj copied from the main checkout points at the wrong paths and produces build errors that look like real code problems.
2. Give each slot its own simulator
The shared simulator is where most parallel sessions break. If two agents install the same bundle ID on the same device, the second install replaces the first app and inherits its data container. Agent one's UI test then runs against agent two's build, and nobody can explain the failure.
Create a simulator per slot and keep its UDID with the worktree:
udid=$(xcrun simctl create "agent-1" com.apple.CoreSimulator.SimDeviceType.iPhone-16)
echo "$udid" > ../packerly-agent-1/.agent/simulator-udidThen every build and test targets that device by ID, never by name:
-destination "platform=iOS Simulator,id=$(cat .agent/simulator-udid)"Destinations by name, such as name=iPhone 16, resolve to whichever matching device Xcode finds first. With several agents running, that is a race.
A dedicated simulator also gives each agent clean state on demand. xcrun simctl erase on its own device does not wipe another agent's half-finished onboarding test.
3. Pin build products to the worktree
Xcode's default DerivedData folder is keyed by the project path, so two worktrees already get separate folders. I still set the path explicitly, for two reasons: the agent can find its own build products and logs without guessing a hash, and deleting the worktree deletes its build output.
xcodebuild build \
-scheme Packerly \
-destination "platform=iOS Simulator,id=$(cat .agent/simulator-udid)" \
-derivedDataPath .agent/DerivedData \
-resultBundlePath ".agent/results/build-$(date +%s).xcresult"Add .agent/ to .gitignore. The result bundle matters more than it looks. When an agent reports a failed build, the .xcresult is the evidence you open, and it should belong to that slot alone.
Swift packages are the one place where sharing is tempting. Each worktree resolving packages from scratch costs time and disk. A shared -clonedSourcePackagesDirPath saves both, but two agents resolving into the same directory at once can contend. My rule is simple: commit Package.resolved, resolve once per worktree at creation time, and do not let agents update package versions in parallel. Dependency changes go through one slot.
4. Cap parallelism by hardware
Each worktree still costs real hardware. Every slot runs its own compiler, indexer, and simulator, and an iOS build can saturate a laptop by itself.
On most machines two or three active slots is the limit before every build gets slower than running them in sequence. Watch for these signs that you are past it:
- builds that took two minutes now take six
- simulators booting slowly or failing to launch the app within the test timeout
- flaky UI tests that pass when run alone
Test parallelism multiplies this. xcodebuild test with parallel testing enabled clones the destination simulator for its workers, so three agents each running parallel tests can mean a dozen simulators. For agent slots I usually disable parallel testing and let the slots provide the concurrency.
5. Write the slot rules where the agent reads them
The agent will not infer any of this. Put it in AGENTS.md, close to the build commands:
## Build and test
- You work only inside this worktree. Never run git commands in other directories.
- Build and test only on the simulator in `.agent/simulator-udid`. Never boot, erase, or delete other simulators.
- Always pass `-derivedDataPath .agent/DerivedData` and a `-resultBundlePath` under `.agent/results/`.
- Do not change package versions. If you need a dependency change, stop and say so.
- Do not run `xcodebuild clean` on shared caches or delete `~/Library/Developer/Xcode/DerivedData`.The last line is there because agents reach for "delete DerivedData" the moment a build fails oddly. In a shared environment that wipes every other slot's incremental state, and the agents then all rebuild from scratch together.
If you drive the simulator through XcodeBuildMCP or a similar tool, give the agent the UDID explicitly in the session setup. Tools that default to "the booted simulator" bring the collision back as soon as a second device is running.
6. Clean up when the branch lands
Slots accumulate. A month of agent sessions leaves a dozen worktrees, a dozen simulators, and tens of gigabytes of build products nobody remembers creating.
Tear down a slot in one script once its branch is merged or abandoned:
udid=$(cat ../packerly-agent-1/.agent/simulator-udid)
xcrun simctl delete "$udid"
git worktree remove ../packerly-agent-1
git branch -d agent/smart-importgit worktree remove refuses to delete a tree with uncommitted changes, which is the right default. If an agent left work behind, you want to look at it before it disappears.
Run git worktree list and xcrun simctl list devices now and then. Anything named agent-* without a matching worktree is a leftover.
7. Keep review serial
The point of parallel slots is that agents can build and test at the same time. Review should stay serial. Each branch comes back with its own result bundle and simulator evidence, and you merge them one at a time, rebasing the next one onto the updated main and rebuilding it before you look.
Two agents producing two green branches does not mean the merged result builds. They each tested against the main they started from. The rebuild after rebase catches the cases where both touched the same model type or project file.
For most indie teams, two slots plus your own checkout is enough. It roughly doubles the work you can hand off without making you the person who has to work out which agent broke the simulator.