Claude Code and Codex for iOS development: setting up Xcode and the Simulator

Claude Code or Codex does useful iOS development work when it has three things: written instructions for your project, a way to build and run the app, and a way to see what it built. One setup described in the documentation combines an AGENTS.md file with XcodeBuildMCP and its tap tools turned on. Both Claude Code and Codex support it, according to XcodeBuildMCP’s docs, and it takes four steps, below. The loop wasn’t run end to end for this page: no server was set up for it and no app was built, so treat it as a documented path and check each step’s output as you go.

Everything here comes from Apple’s, Anthropic’s, OpenAI’s and XcodeBuildMCP’s documentation, rechecked on September 19, 2026, and from the help text of Xcode 27.0 (27A266a), Claude Code 2.1.277, Codex CLI 0.149.1 and XcodeBuildMCP 2.6.2. A later section covers publishable screenshots with Moonjar, a Mac app I make (our product, in early access), which also made the Ellie images on this page. Ellie is the planner I build.

1. Write down how your project builds

Both agents read a Markdown file from your repo at the start of every session. Codex reads AGENTS.md. Claude Code reads CLAUDE.md, and from version 2.1.277 it reads AGENTS.md when there’s no CLAUDE.md, so one AGENTS.md can usually serve both. (In some sessions, such as on Amazon Bedrock or with telemetry off, Claude Code can’t read AGENTS.md; a CLAUDE.md containing the line @AGENTS.md works there.)

Put in what the agent would otherwise have to discover or guess. A starting section, shaped by what OpenAI’s iOS pages and XcodeBuildMCP’s own instructions ask an agent to confirm:

## iOS
- Project: MyApp.xcodeproj, scheme MyApp, Debug
- Simulator: iPhone 17 Pro, latest iOS
- Build and run with XcodeBuildMCP; check session defaults before the first build
- Tests: run the narrowest test that covers the change
- Before saying a UI change works, run it and take a screenshot
- Tap controls by accessibility label, not coordinates, and tell me when a control has no label

Name the build configuration: since XcodeBuildMCP 2.7.0, a build with no configuration set follows the scheme’s own instead of defaulting to Debug.

2. Add XcodeBuildMCP

XcodeBuildMCP is an open-source (MIT) MCP server and command-line tool for agents working on iOS and macOS projects, hosted under Sentry’s GitHub organization. It needs macOS 14.5 or later, Xcode 16 or later, and Node.js 18 or later unless you install it with Homebrew. Its latest release on September 19, 2026 was v2.7.0, which added support for Xcode 27’s Device Hub simulators to its UI automation tools.

For Claude Code, run this from your project folder:

claude mcp add XcodeBuildMCP \
  -- npx -y xcodebuildmcp@latest mcp

For Codex, add a block to ~/.codex/config.toml instead of using codex mcp add, because Codex gives an MCP tool call 60 seconds by default, a build can take longer, and codex mcp add has no timeout option:

[mcp_servers.XcodeBuildMCP]
command = "npx"
args = ["-y", "xcodebuildmcp@latest", "mcp"]
tool_timeout_sec = 600

Keep the final mcp in both: it’s the subcommand that starts the server, and some setup guides that rank for this search leave it out. Claude Code saves the server in local scope, which loads only in the project where you added it; add --scope user to have it everywhere. Check either with claude mcp list or codex mcp list.

3. Turn on the tools that tap

Out of the box, XcodeBuildMCP exposes only its simulator workflow: build, run, test, install, launch with logs, screenshots, video recording and a snapshot of the UI tree. Tapping, swiping and typing are in the ui-automation workflow, which is off by default. An XcodeBuildMCP server already configured in the Claude Code session that drafted this page (its version wasn’t recorded) listed 24 tools, none of which could tap. Create .xcodebuildmcp/config.yaml at the project root:

schemaVersion: 1
enabledWorkflows: ["simulator", "ui-automation"]

Or run xcodebuildmcp setup, which writes the file with a wizard and can save your project, scheme and simulator as session defaults too. Restart the agent after changing it. Add other workflows (debugging, device, macos, swift-package, xcode-ide) only when you need them: every tool the server lists costs context.

4. Run one change through the loop, and ask for proof

OpenAI’s two iOS pages describe this loop for Codex, and none of the steps depend on Codex itself: pick the project, scheme and simulator once; build and launch; confirm the screen with a UI snapshot or a screenshot before touching anything; drive the path by accessibility labels; collect screenshots and logs; make the fix; run the same path again. A prompt in that shape:

Add a Clear completed button to the Today list. Use XcodeBuildMCP: check the session defaults, then build and run on the iPhone 17 Pro simulator. Open Today, tap Clear completed by its accessibility label, and take a screenshot before and after. Tell me the scheme, the simulator and the checks you ran.

It’s working when the reply names the scheme and simulator it used, reports a successful build, and shows a before and an after screenshot of the screen you asked about. If it had to tap by coordinates because a control has no label, treat that as a small testability fix to make too. Naming the server in the prompt matters once the agent has more than one tool that can take a screenshot.

• Xcode. Xcode 27 (27A266a) came out on September 14, 2026, and it needs macOS Tahoe 26.6 or later. Xcode’s MCP server arrived in Xcode 26.3.

• Device Hub. In Xcode 27, a simulator you run your app on opens in Device Hub, which replaces the Simulator app. xcrun simctl is still there.

• Claude Code needs a Pro, Max, Team, Enterprise or Console account; the free Claude plan doesn’t include it.

• Codex comes with ChatGPT’s Free, Go, Plus, Pro, Business, Enterprise and Edu plans, or works with an API key, per OpenAI’s pricing page (checked September 18, 2026). Usage limits differ by plan.

The same task wasn’t run through both for this page, so there’s no winner here. The setup differs in a few documented ways:

• Plans. Claude Code: Pro, Max, Team, Enterprise or Console. Codex: ChatGPT Free and up, or an API key.

• Instructions. Claude Code: CLAUDE.md; it reads AGENTS.md if there’s no CLAUDE.md. Codex: AGENTS.md.

• Servers saved in. Claude Code: ~/.claude.json, or .mcp.json to share. Codex: ~/.codex/config.toml, or .codex/config.toml in trusted projects.

• Tool call timeout. Claude Code: about 28 hours, or 30 idle minutes for a local server. Codex: 60 seconds unless you raise it.

• Skills folder. Claude Code: .claude/skills/. Codex: .agents/skills/.

• Simulator without a server. Claude Code: the desktop app’s Simulator pane, or computer use in the CLI. Codex: Computer Use in the ChatGPT desktop app.

• Inside Xcode. Claude Agent and Codex, both in Xcode 26.3 and later.

OpenAI also publishes two iOS pages for Codex, Build for iOS and Debug in iOS simulator; most of their advice is about XcodeBuildMCP and the build loop rather than Codex itself.

Xcode 26.3 and later include an MCP server that gives agents outside Xcode Xcode’s own tools. From Apple’s page on giving external agents access to Xcode:

1. In Xcode, choose Xcode > Settings, select Intelligence, and under Model Context Protocol turn on “Allow external agents to use Xcode tools.”

2. Register Xcode’s bridge with your agent, using the commands below.

3. Check it with claude mcp list or codex mcp list.

4. Open your project in Xcode before you prompt the agent. Xcode tells you when an external agent connects and when it’s active.

Screenshot of Apple’s Giving external agents access to Xcode page, captured September 18, 2026 with Moonjar, which drew the box. The window in it is Apple’s own screenshot of Xcode’s Intelligence settings.

# Claude Code
claude mcp add --transport stdio xcode -- xcrun mcpbridge
# Codex
codex mcp add xcode -- xcrun mcpbridge

What the agent gets: Apple’s Xcode 26.3 announcement says agents can search documentation, explore file structures, update project settings, and check their work visually by capturing Xcode Previews and iterating through builds and fixes. The Xcode 27 release notes add tools to drive the debugger, switch schemes and run destinations, read and change build settings, entitlements and Info.plist keys, edit String Catalog translations, and render previews in variants. The list changes with each Xcode version, so ask the agent to list the xcode server’s tools rather than relying on someone else’s list.

xcrun mcpbridge is a bridge to a running Xcode. Its help text in Xcode 27.0 says it connects to the Xcode selected by xcode-select unless MCP_XCODE_PID names another. Xcode 27 also previews a server that works without an open workspace: sudo xcrun mcp-server enable, then xcrun mcp-server status to check it. The release notes call it an early preview and say its --unsafe-always-allow-all-agents option, meant for unattended machines, isn’t recommended at your desk.

XcodeBuildMCP and Xcode’s server overlap on builds. XcodeBuildMCP runs builds through xcodebuild, and reaches Xcode’s IDE-only tools (preview rendering, the Issue Navigator, documentation search) through its optional xcode-ide workflow, which passes Xcode’s own server through on Xcode 26.3 and later.

• Timeouts. XcodeBuildMCP’s docs suggest 600 seconds for Codex and note that Codex ignores a top-level tool_timeout_sec for MCP tool calls; put it in the server’s own block. Claude Code has no short default: without MCP_TOOL_TIMEOUT or a per-server timeout, the limit is about 28 hours, but a call to a local server that sends no response or progress for 30 minutes is stopped.

• Defaults. Its setup page shows the agent calling session_set_defaults with the project, scheme and simulator, then build_run_sim with no arguments on every later call.

• Telemetry. XcodeBuildMCP reports its own runtime errors to Sentry. Its privacy page says tool inputs and outputs, source code and build products aren’t sent, and XCODEBUILDMCP_SENTRY_DISABLED=true turns it off.

• Homebrew instead of npx. brew tap getsentry/xcodebuildmcp, then brew install xcodebuildmcp, and use xcodebuildmcp mcp as the command.

Claude Code Desktop’s iOS Simulator pane

In the Code tab of the Claude desktop app, the Simulator opens in a pane next to the conversation whenever Claude builds, runs or checks your app, and streams the device live. Ask Claude to build the app and run it in the simulator, and allow the device the first time. You can tap in the pane yourself while Claude works, and save a screenshot (Command-S) or a screen recording (Command-R) to your Desktop from the pane. Anthropic’s Simulator pane docs, rechecked September 19, 2026, say:

• It’s a public beta on macOS, on Pro, Max, Team and Enterprise plans, except Enterprise organizations with a HIPAA configuration, and needs Claude Desktop 1.24012.0 or later.

• It doesn’t yet work with Xcode 27. Use Xcode 26.x; if Xcode 27 is also installed, point xcode-select at the 26.x copy.

• It drives the simulator directly, so it doesn’t need computer use and doesn’t take over your screen.

• Claude’s screenshots of the device are sent to Anthropic, so don’t sign in to real accounts on a simulator Claude uses.

• It works in local sessions only, with simulators, not a physical iPhone.

Computer use, in Claude Code and in Codex

From the terminal, Claude Code reaches the Simulator through computer use, which controls it on your screen the way you would with a mouse. Anthropic describes it as a research preview on macOS for Pro and Max plans, in interactive sessions only; it’s off until you enable the built-in computer-use server from /mcp, and it asks for the Accessibility and Screen Recording permissions. Claude uses an MCP server or the shell first when one can do the job.

For Codex, OpenAI’s Computer Use docs list testing an “iOS simulator flow” among the good uses of the Computer Use plugin in the ChatGPT desktop app, on macOS or Windows, with the same two macOS permissions. The same docs say to prefer a dedicated plugin or MCP server when the target app has one.

No server at all: xcodebuild and simctl

OpenAI’s Build for iOS page suggests starting “CLI-first” with Apple’s xcodebuild, and adding XcodeBuildMCP once schemes, simulator control, screenshots, logs and UI interaction matter. From the shell, the build step looks like this, checked against xcodebuild -help in Xcode 27.0:

xcodebuild -list
xcodebuild -scheme MyApp \
  -destination 'platform=iOS Simulator,name=iPhone 17 Pro' \
  -derivedDataPath build \
  build

That only builds. It doesn’t install the new build or open it, so a screenshot taken now shows whatever was already on the simulator’s screen. -derivedDataPath puts the build products in a folder you name (here build), which is where you’ll find the .app. Three more commands, as xcrun simctl help in Xcode 27.0 documents them, get the build on screen and capture it; they weren’t run for this page:

• xcrun simctl install <device> <path to MyApp.app>, once the simulator is booted.

• xcrun simctl launch <device> <bundle identifier>. The bundle identifier is among the settings xcodebuild -scheme MyApp -showBuildSettings prints, as PRODUCT_BUNDLE_IDENTIFIER.

• xcrun simctl io <device> screenshot screen.png.

For <device>, use the UDID from xcrun simctl list devices booted. The word booted also works, but the help says that when several simulators are running, simctl picks one of them. Tracking the app path, bundle ID and device yourself is the bookkeeping XcodeBuildMCP’s simulator tools do for you: its tool list includes finding the built app’s path and bundle ID, installing, launching and taking the screenshot.

ios-simulator-mcp, for Simulator control only

ios-simulator-mcp by Joshua Yoes (MIT) only drives the Simulator: its README lists tools to read the accessibility tree, tap, type, swipe, take screenshots, record video, and install and launch apps, but none to build. It needs Node.js 20 or later and Facebook’s IDB. It overlaps with XcodeBuildMCP’s ui-automation workflow, so running both gives the agent two sets of tap and screenshot tools to choose between.

Xcode 26.3 added Anthropic’s Claude Agent and OpenAI’s Codex to Xcode’s coding assistant. To turn one on, choose Xcode > Settings > Intelligence, click Get next to the agent under Agents, click Install, then sign in from the agent’s Account row. An agent you pick there gets Xcode’s tools automatically, building and testing included. The Xcode 27 release notes add that agents can boot simulators, install and launch apps, synthesize touch events and capture screenshots to check UI behavior, along with plans you review before the agent goes ahead.

Settings for these agents live in their own folders under ~/Library/Developer/Xcode/CodingAssistant/ (such as ClaudeAgentConfig and codex) and only affect agents launched in Xcode. A server you added to Claude Code in Terminal isn’t there inside Xcode until you add it for Xcode’s agent too. XcodeBuildMCP’s clients page shows how: for Claude Agent in ClaudeAgentConfig/.claude.json, and for Codex in a .codex/config.toml at the project’s root, each with a zsh wrapper, because agents inside Xcode start with a minimal PATH and may not find npx.

Pick Xcode’s agents if you work in Xcode and want diffs, plans and preview snapshots next to the code. Pick Claude Code or Codex in Terminal if you want the same agent and settings across your other repos, and connect Xcode’s tools over MCP when you need them.

A skill is a folder with a SKILL.md file that the agent loads when a task matches it. Claude Code reads skills from .claude/skills/ in the project or ~/.claude/skills/; Codex reads .agents/skills/ in the repository or ~/.agents/skills/.

• Apple’s skills, from Xcode 27. xcrun agent skills export on Xcode 27.0 wrote ten Apple-written skills to a folder: swiftui-specialist, swiftui-whats-new-27, uikit-app-modernization, modernize-tests, device-interaction, app-intents-specialist, app-intents-whats-new-27, building-document-based-swiftui-applications, audit-xcode-security-settings and adopt-c-bounds-safety. Each is an ordinary SKILL.md folder. device-interaction is written around Xcode’s own DeviceInteraction tools; using any of them from Claude Code or Codex wasn’t checked.

• XcodeBuildMCP’s two skills. xcodebuildmcp init installs its CLI skill, for an agent that runs the xcodebuildmcp command in the shell, into each client it finds. The MCP skill is optional when you use the server, and Claude Code doesn’t need it.

• OpenAI’s Build iOS Apps plugin for Codex, whose iOS debugger agent runs the reproduce, fix and verify loop on the Simulator through XcodeBuildMCP.

• Community SwiftUI skills. OpenAI’s Build for iOS page links Antoine van der Lee’s SwiftUI expert skill, Paul Hudson’s SwiftUI Pro and several of Thomas Ricouard’s skills for Liquid Glass, SwiftUI performance and Swift concurrency.

• Claude Code’s /run and /verify. These bundled skills build and run your app to confirm a change. Anthropic’s docs say they infer the launch from files like your README or Makefile, that this gets unreliable when a project needs more than a standard launch, and that /run-skill-generator records a working recipe as a project skill for that case.

The screenshots in the loop above are for the agent to check its work. An image for a pull request, a release note, a help article or the App Store needs more: a clean 9:41 status bar, a frame, and the one row that matters pointed out. If you’re doing that by hand, the Simulator screenshot guide covers the status bar and frames, and recording the Simulator with visible taps covers video.

Moonjar (our product) is a Mac app with an MCP server for that step. You add it to Claude Code with claude mcp add, and to Codex with a config.toml block like the XcodeBuildMCP one above, since a long render or recording needs a longer tool_timeout_sec. By default its Simulator captures set a 9:41 status bar and save the screen’s UI tree, so a design can lift a row by naming it. It also captures Mac windows and web pages, and it records the Simulator with the agent’s taps logged, so the agent can zoom to them and draw them in the cut.

On September 18, 2026, Claude, working in Claude Code, used Moonjar’s tools on a test iPhone 17 Pro Simulator running Ellie with its demo data: it listed the installed apps, read the screen’s accessibility elements, opened two screens by deep link and captured three screens, each 1206 x 2622 with a 9:41 status bar and its UI tree saved. Later that day it styled one of those captures in one call, naming the row to lift: create_design with highlight {label: 'Restart the changelog newsletter'} found that row in the saved tree.

Left: a Simulator capture an AI agent took through Moonjar on September 18, 2026, from Ellie’s demo data, 1206 x 2622 with a 9:41 status bar. Right: the same capture styled by the agent, with the row it named lifted. Photo by Bernd Dittrich on Unsplash.

If Codex also has XcodeBuildMCP or another screenshot tool, start the request with “Use the Moonjar MCP tools to…”, because Codex may otherwise pick a different tool. Moonjar runs on the Mac only. The full App Store version of this workflow is in App Store screenshots with Claude Code, and the recording version is in Claude Code video editing. For how Moonjar connects to both agents, see Moonjar with Claude Code and Codex, or see what Moonjar does.

• Codex stops with “timed out awaiting tools/call after 60s”. Add tool_timeout_sec to that server’s own block in config.toml, as above. A server that’s slow to start needs startup_timeout_sec, which defaults to 10 seconds.

• The xcode server is listed but can’t reach your project. Open the project in Xcode first, and allow the connection when Xcode asks. With several copies of Xcode installed, set MCP_XCODE_PID to the one you want.

• Claude Code has the server in one folder only. That’s local scope, the default. Re-add it with --scope user for every project, or --scope project to write a .mcp.json you can commit.

• A server from .mcp.json says “Pending approval”. Run claude in the project, accept the workspace trust dialog and approve it; a cloned repository can’t approve its own servers.

• The agent can’t tap. XcodeBuildMCP’s default workflow has no tap tools. Add ui-automation to enabledWorkflows, then restart the agent. On Xcode 27, use XcodeBuildMCP 2.7.0 or later, the release that added Device Hub support to UI automation.

• Claude Code Desktop’s Simulator pane says no simulators were found. With Xcode 27 selected, attaching a device fails or the pane lists none. Install Xcode 26.x beside it and select that copy with sudo xcode-select -s and its path; xcode-select -p shows which one is selected.

• XcodeBuildMCP won’t start inside Xcode’s agents. They start with a minimal PATH; XcodeBuildMCP’s troubleshooting page gives a zsh -lc wrapper that finds npx.

• Tool output is cut off in Claude Code. Claude Code warns above 10,000 tokens of MCP output and limits it to 25,000 by default. MAX_MCP_OUTPUT_TOKENS raises the limit.

• The agent uses the wrong server’s screenshot tool. Name the server in the prompt.

How this was made: commands and options were checked against the help text of the versions named at the top on September 18, 2026, and the vendors’ documentation and XcodeBuildMCP’s releases were rechecked on September 19. No server was set up and no app was built for this page. The Xcode settings image is a capture of Apple’s public documentation page, taken and boxed with Moonjar (our product) on September 18. The Ellie images, the cover included, were made with Moonjar from Simulator captures of Ellie’s demo data taken the same day; their background photo is by Bernd Dittrich on Unsplash. This page was drafted with AI assistance.