Use worktree-ios-dev-tool for every non-interactive iOS build or simulator task. Keep xcodebuildmcp-cli for debugging, UI automation, and log streaming.
Decision
- Build / test / run / clean / package test / wipe derived data →
worktree-ios-dev-tool <verb>(top-level). - Project lifecycle (init, inspect config, doctor) →
worktree-ios-dev-tool proj <verb>. - Simulator lifecycle (pick, boot, shutdown, list, recreate, remove, cleanup, du, prune) →
worktree-ios-dev-tool sim <verb>. - Debug sessions, breakpoints, log streaming, UI automation (tap / swipe / screenshot), archive, export IPA, TestFlight →
xcodebuildmcp-cliskill. - Never use
swift testfor local Swift packages — useworktree-ios-dev-tool test-packageinstead.
One-time machine setup
uv tool install --editable /abs/path/to/worktree-ios-dev-tool/worktree_ios_dev_tool
Requires uv on PATH and ~/.local/bin on PATH.
Upgrade with uv tool upgrade worktree-ios-dev-tool. Editable installs pick up Python source edits automatically.
Optional: brew install mint enables xcbeautify for prettier xcodebuild output. The tool auto-detects mint on PATH; without it, builds still work but emit a one-line stderr note suggesting the install. worktree-ios-dev-tool proj doctor reports mint status.
Per-worktree setup
From anywhere inside the worktree:
worktree-ios-dev-tool proj init # creates worktree-ios-dev/, seeds project.toml, updates .gitignore
worktree-ios-dev-tool sim pick # first run: interactive picker; writes [simulators.default] to simulator.toml
For peer-to-peer scenarios that need a second sim:
worktree-ios-dev-tool sim pick peer
worktree-ios-dev-tool run --sim peer
Agent (non-interactive) usage
When stdin is not a TTY the tool switches automatically to flat [worktree-ios-dev-tool] <msg> output. For proj init, supply --project and --scheme explicitly and add --yes to suppress prompts:
worktree-ios-dev-tool proj init \
--project ios/App.xcodeproj \
--scheme App \
--yes
sim pick auto-selects the first available device and latest runtime when stdin is not a TTY. Use --device / --runtime to pick explicitly (e.g. --device "iPhone 17 Pro" --runtime "iOS 26.2"); pass --all-devices if the default iPhone 17 Pro filter is too narrow. sim cleanup and sim prune require --yes outside a TTY.
Verb reference
proj
| Verb | Use for |
|---|---|
proj init |
Scaffold worktree-ios-dev/ in a new worktree. Idempotent. --force re-seeds project.toml; never touches simulator.toml. |
proj config |
Print resolved project + simulators view as JSON. Debugging. |
proj doctor |
Sanity checks: tooling, project.toml, simulators, project path. Run this first when something's off. Missing simulator.toml is a warn, not a fail. |
sim
| Verb | Use for |
|---|---|
sim pick [<label>] |
Pick + create + boot a simulator. Interactive on TTY, auto-selects first device/runtime otherwise. --device / --runtime for explicit choice. <label> defaults to default. |
sim boot [<label>] / sim boot --all |
Boot one configured sim or every sim. |
sim shutdown [<label>] / sim shutdown --all |
Shutdown one or all. |
sim list / sim list --global |
List this worktree's sims (default) or every managed sim grouped by worktree. |
sim recreate <label> |
Destroy + re-pick + re-boot. Accepts --device / --runtime too. Always requires explicit label. |
sim remove <label> |
Drop the entry from simulator.toml. Default keeps the simctl device; --destroy deletes it too. |
sim cleanup |
Tear down every sim owned by this worktree (prefix scan, name-based) and delete simulator.toml. Run before git worktree remove. |
sim du / sim du --this-worktree |
Disk-usage report for managed simulators, grouped by worktree. |
sim prune |
Find managed sims whose worktree is gone (via git worktree list) and delete them. |
Build verbs (top-level)
| Verb | Use for |
|---|---|
build |
xcodebuild build. Flags: --release, --scheme <name>, --sim <label>. |
test |
xcodebuild test. Flags: --release, --scheme <name>, --only-testing, --skip-testing, --sim <label>. |
run |
Build → install → launch. Flags: --release, --sim <label>. |
clean |
xcodebuild clean. |
wipe-derived |
rm -rf worktree-ios-dev/derivedData. Prompts unless --yes. |
test-package <Name> |
Test a local Swift package via xcodebuild. Flags: --sim <label>. |
--sim <label> is required only when more than one entry exists under [simulators.*] in simulator.toml. Single-sim setups inherit the only entry.
Global flags
--project-toml <path>— override walk-up discovery (was--configpre-2026-05-05).-v/--verbose— stream subprocess output, show tracebacks on error.
Exit codes
0ok1user error (bad CLI args, bad config, verb refused)2environment error (project.toml not found, xcodebuild / simctl missing)3subprocess failure (xcodebuild / simctl returned non-zero; upstream code is included in the message)
Common mistakes
- Running any verb without
proj initfirst → exit 2 with discovery error. Runproj init. - Skipping
sim pick→ any verb that needs a simulator errors with "runsim pickfirst." - Editing
[simulators.*].udidby hand → prefersim recreate <label>. - Using
xcodebuildmcp-clifor a vanilla build/test → goes through the wrong path; useworktree-ios-dev-toolinstead. - Encountering a legacy
worktree-ios-dev/config.toml→ manual migration: read it, runproj init --force, thensim pick, thenrm config.toml. The tool refuses to run with a legacy file present. - Forgetting
sim cleanupbeforegit worktree remove→ orphaned simulators accumulate.sim prunecleans them later, or runsim duto see what's piling up.