use-cases/ios-simulator-bug-debugging.md Codex Docs, 2026-04-22 18:29 UTC → 2026-05-11 18:00 UTC

1# Debug in iOS simulator | Codex use cases1---

2name: Debug in iOS simulator

3tagline: Use Codex and XcodeBuildMCP to drive your app in iOS Simulator, capture

4 evidence, and iterate toward a fix.

5summary: Use Codex to discover the right Xcode scheme and simulator, launch the

6 app, inspect the UI tree, tap, type, swipe, capture screenshots and logs,

7 attach LLDB when needed, and turn a vague bug report into a small verified

8 fix.

9skills:

10 - token: build-ios-apps

11 url: https://github.com/openai/plugins/tree/main/plugins/build-ios-apps

12 description: Use the iOS debugger agent to build, launch, inspect, and drive an

13 app on a simulator with XcodeBuildMCP, then capture logs, screenshots, and

14 stack traces while Codex narrows the bug.

15bestFor:

16 - UI bugs that only show up after a specific tap, scroll, or form entry path

17 in Simulator

18 - Crashes, hangs, or broken navigation where Codex needs logs, screenshots,

19 view hierarchy state, and a debugger backtrace before editing code

20 - Teams that want Codex to own the reproduce-fix-verify loop instead of asking

21 a human to manually click through every state

22starterPrompt:

23 title: Reproduce, Diagnose, and Fix One Simulator Bug

24 body: >-

25 Use the Build iOS Apps plugin and XcodeBuildMCP to reproduce this bug

26 directly in Simulator, diagnose the root cause, and implement a small fix.

2 27 

3Need

4 28 

5App observability29 Bug report:

6 30 

7Default options31 [Describe the expected behavior, the actual bug, and any known screen or

32 account setup.]

8 33 

9`Logger`, `OSLog`, LLDB, and Simulator screenshots

10 34 

11Why it's needed35 Constraints:

12 36 

13Codex 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 - First check whether a project, scheme, and simulator are already selected.

38 If not, discover the right Xcode project or workspace, pick the app scheme,

39 choose a simulator, and reuse that setup for the rest of the session.

40 

41 - Build and launch the app in Simulator, then confirm the right screen is

42 visible with a UI snapshot or screenshot before you start interacting with

43 it.

44 

45 - Drive the exact reproduction path yourself by tapping, typing, scrolling,

46 and swiping in the simulator. Prefer accessibility labels or IDs over raw

47 coordinates, and re-read the UI hierarchy before the next action when the

48 layout changes.

49 

50 - Capture evidence while you debug: screenshots for visual state, simulator

51 logs around the failure, and LLDB stack frames or variables if the bug looks

52 like a crash or hang.

53 

54 - If the simulator is not already booted, boot one and tell me which device

55 and OS you chose. If credentials or a special fixture are required, pause

56 and ask only for that missing input.

57 

58 - Make the smallest code change that addresses the bug, then rerun the

59 simulator flow and tell me exactly how you verified the fix.

60 

61 

62 Deliver:

63 

64 - the reproduction steps Codex executed

65 

66 - the key screenshots, logs, or stack details that explained the bug

67 

68 - the code fix and why it works

69 

70 - the simulator and scheme used for final verification

71relatedLinks:

72 - label: Build iOS Apps plugin

73 url: https://github.com/openai/plugins/tree/main/plugins/build-ios-apps

74 - label: Model Context Protocol

75 url: /codex/mcp

76 - label: Agent skills

77 url: /codex/skills

78techStack:

79 - need: Simulator automation

80 goodDefault: "[XcodeBuildMCP](https://www.xcodebuildmcp.com/)"

81 why: The current tool surface covers simulator setup, build and launch, UI

82 snapshots, taps, typing, gestures, screenshots, log capture, and debugger

83 attachment.

84 - need: Agent workflow

85 goodDefault: "[Build iOS Apps

86 plugin](https://github.com/openai/plugins/tree/main/plugins/build-ios-app\

87 s)"

88 why: The plugin's iOS debugger agent gives Codex a clear simulator-first loop

89 for reproducing a bug, gathering evidence, and validating the fix after

90 each change.

91 - need: App observability

92 goodDefault: "`Logger`, `OSLog`, LLDB, and Simulator screenshots"

93 why: Codex can use logs and debugger state to explain what broke, then save

94 screenshots to prove the exact UI state before and after the fix.

95---

96 

97## Give Codex the whole simulator loop

98 

99This 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.

100 

101Use 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.

102 

103When 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.

104 

105## Leverage what XcodeBuildMCP can do

106 

107These are the practical capability groups to prompt Codex to use:

108 

109- 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.

110- 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.

111- 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.

112- 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.

113 

114The 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.

115 

116## Turn a vague bug into a reproducible script

117 

118The 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.

119 

120## Practical tips

121 

122### Ask for evidence, not just a fix

123 

124Request 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."

125 

126### Prefer accessibility labels over coordinates

127 

128If 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.

129 

130### Keep one bug per run

131 

132A 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.