This page contains 7 additions and 123 deletions.
Need
App observability
Default options
Logger, OSLog, LLDB, and Simulator screenshots
Why it's needed
Codex can use logs and debugger state to explain what broke, then save screenshots to prove the exact UI state before and after the fix.
11name: Debug in iOS simulator# Debug in iOS simulator | Codex use cases
2tagline: Use Codex and XcodeBuildMCP to drive your app in iOS Simulator, capture
3 evidence, and iterate toward a fix.
4summary: Use Codex to discover the right Xcode scheme and simulator, launch the
5 app, inspect the UI tree, tap, type, swipe, capture screenshots and logs,
6 attach LLDB when needed, and turn a vague bug report into a small verified
7 fix.
8skills:
9 - token: build-ios-apps
10 url: https://github.com/openai/plugins/tree/main/plugins/build-ios-apps
11 description: Use the iOS debugger agent to build, launch, inspect, and drive an
12 app on a simulator with XcodeBuildMCP, then capture logs, screenshots, and
13 stack traces while Codex narrows the bug.
14bestFor:
15 - UI bugs that only show up after a specific tap, scroll, or form entry path
16 in Simulator
17 - Crashes, hangs, or broken navigation where Codex needs logs, screenshots,
18 view hierarchy state, and a debugger backtrace before editing code
19 - Teams that want Codex to own the reproduce-fix-verify loop instead of asking
20 a human to manually click through every state
21starterPrompt:
22 title: Reproduce, Diagnose, and Fix One Simulator Bug
23 body: >-
24 Use the Build iOS Apps plugin and XcodeBuildMCP to reproduce this bug
25 directly in Simulator, diagnose the root cause, and implement a small fix.
26 2
3Need
27 4
285 Bug report:App observability
29 6
307 [Describe the expected behavior, the actual bug, and any known screen orDefault options
31 account setup.]
32 8
9`Logger`, `OSLog`, LLDB, and Simulator screenshots
33 10
3411 Constraints:Why it's needed
35 12
3613 - First check whether a project, scheme, and simulator are already selected.Codex can use logs and debugger state to explain what broke, then save screenshots to prove the exact UI state before and after the fix.
37 If not, discover the right Xcode project or workspace, pick the app scheme,
38 choose a simulator, and reuse that setup for the rest of the session.
39 14
40 - Build and launch the app in Simulator, then confirm the right screen is
41 visible with a UI snapshot or screenshot before you start interacting with
42 it.
43
44 - Drive the exact reproduction path yourself by tapping, typing, scrolling,
45 and swiping in the simulator. Prefer accessibility labels or IDs over raw
46 coordinates, and re-read the UI hierarchy before the next action when the
47 layout changes.
48
49 - Capture evidence while you debug: screenshots for visual state, simulator
50 logs around the failure, and LLDB stack frames or variables if the bug looks
51 like a crash or hang.
52
53 - If the simulator is not already booted, boot one and tell me which device
54 and OS you chose. If credentials or a special fixture are required, pause
55 and ask only for that missing input.
56
57 - Make the smallest code change that addresses the bug, then rerun the
58 simulator flow and tell me exactly how you verified the fix.
59
60
61 Deliver:
62
63 - the reproduction steps Codex executed
64
65 - the key screenshots, logs, or stack details that explained the bug
66
67 - the code fix and why it works
68
69 - the simulator and scheme used for final verification
70relatedLinks:
71 - label: Build iOS Apps plugin
72 url: https://github.com/openai/plugins/tree/main/plugins/build-ios-apps
73 - label: Model Context Protocol
74 url: /codex/mcp
75 - label: Agent skills
76 url: /codex/skills
77techStack:
78 - need: Simulator automation
79 goodDefault: "[XcodeBuildMCP](https://www.xcodebuildmcp.com/)"
80 why: The current tool surface covers simulator setup, build and launch, UI
81 snapshots, taps, typing, gestures, screenshots, log capture, and debugger
82 attachment.
83 - need: Agent workflow
84 goodDefault: "[Build iOS Apps
85 plugin](https://github.com/openai/plugins/tree/main/plugins/build-ios-app\
86 s)"
87 why: The plugin's iOS debugger agent gives Codex a clear simulator-first loop
88 for reproducing a bug, gathering evidence, and validating the fix after
89 each change.
90 - need: App observability
91 goodDefault: "`Logger`, `OSLog`, LLDB, and Simulator screenshots"
92 why: Codex can use logs and debugger state to explain what broke, then save
93 screenshots to prove the exact UI state before and after the fix.
94
95## Give Codex the whole simulator loop
96
97This use case works best when Codex owns the full loop: choose the right app target, launch the app in Simulator, inspect the current screen, perform the reproduction steps, gather logs and screenshots, inspect a stack trace if needed, patch the code, and rerun the same path to prove the bug is gone.
98
99Use the [Build iOS Apps plugin](https://github.com/openai/plugins/tree/main/plugins/build-ios-apps) when you want that loop to stay agentic. Its iOS debugger workflow is built around XcodeBuildMCP, which means Codex can interact with a booted simulator and gather the same evidence a human would normally collect by hand.
100
101When XcodeBuildMCP is configured with simulator automation, UI automation, debugging, and logging workflows, Codex can own the full reproduce-debug-verify loop. If Codex has not picked a project, scheme, and simulator yet, ask it to discover those first and reuse that setup for the rest of the session.
102
103## Leverage what XcodeBuildMCP can do
104
105These are the practical capability groups to prompt Codex to use:
106
107- Project and simulator discovery: check whether Codex already knows which app target and simulator to use, discover the Xcode project or workspace, enumerate schemes, find or boot a simulator, and keep that setup stable for future build/run steps.
108- Build and launch control: build the active app target, install and launch the simulator build, relaunch with log capture when needed, and resolve the app bundle id if Codex needs to inspect app-specific runtime logs.
109- UI inspection and interaction: read the on-screen accessibility hierarchy, take screenshots, tap controls, type into fields, scroll through lists, and perform edge swipes or other simulator gestures.
110- Logs and debugger state: stream simulator logs, attach LLDB to the running app, set breakpoints, inspect stack frames and local variables, and run debugger commands when a crash or hang needs deeper inspection.
111
112The key habit is to ask Codex to inspect the view tree before it taps. XcodeBuildMCP exposes the accessibility hierarchy plus coordinates, so Codex can prefer stable labels or element IDs instead of guessing raw screen positions.
113
114## Turn a vague bug into a reproducible script
115
116The iOS debugger skill is most effective when your prompt gives one concrete bug and one expected outcome, then lets Codex drive the app and collect evidence autonomously. If a login, deep link, or test fixture is required, say that once and ask Codex to pause only when that missing input blocks progress.
117
118## Practical tips
119
120### Ask for evidence, not just a fix
121
122Request the exact simulator, scheme, screenshots, log snippets, and stack details that Codex used to explain the bug. That makes the final patch much easier to review than "I think this should fix it."
123
124### Prefer accessibility labels over coordinates
125
126If Codex has to tap by coordinates because a control has no stable label or accessibility identifier, ask it to call that out. That is often a signal that the bug fix should include a small UI testability improvement too.
127
128### Keep one bug per run
129
130A simulator-driven debugging loop is powerful, but it is still easier to trust when one prompt targets one failure mode. Ask Codex to finish one reproduce-fix-verify cycle before expanding to adjacent issues.
