Codex for iOS development: AGENTS.md, Xcode tools and skills

Codex can write Swift without any setup, but on an iOS project it only becomes reliable once it can build the app, see what the simulator shows, and follow your project's rules. OpenAI's own iOS use-case page recommends exactly that progression: keep the loop CLI-first with xcodebuild, then add an MCP server and focused SwiftUI skills "when the work gets deeper" (OpenAI). This guide walks through the four layers in order and links each tool to its entry on SwiftSkills.

Short answer: put project rules in AGENTS.md, connect Xcode's own tools with codex mcp add xcode -- xcrun mcpbridge, add MobileBuildMCP for simulator builds, screenshots and UI automation, and drop SwiftUI skills into .agents/skills.

1. Start CLI-first with xcodebuild

For a first pass you often need no MCP server or skill at all. OpenAI's guidance is to let Codex scaffold the app and a small build-and-launch script, and to stay in the terminal: Apple's xcodebuild can list schemes and run build, test, archive, build-for-testing and test-without-building actions, which keeps Codex in an agentic loop instead of bouncing into the Xcode GUI. If you prefer a project generator, the same page names Tuist as an option (OpenAI).

Two habits from that page are worth copying into every prompt: tell Codex whether the repo is greenfield or an existing Xcode project, and ask it to run "the narrowest command that actually proves the contract you touched" before a full build.

2. Give Codex your project rules with AGENTS.md

Codex reads AGENTS.md files before doing any work. It first reads a global file in ~/.codex (AGENTS.override.md if present, otherwise AGENTS.md), then walks from the project root down to your working directory and reads at most one file per directory. Files closer to your working directory come later and override earlier guidance. The combined size is capped by project_doc_max_bytes, 32 KiB by default (OpenAI).

For an iOS repo, a root AGENTS.md typically states the deployment target, the scheme and simulator to use, which build and test commands prove a change, and the SwiftUI conventions you want (for example @Observable instead of ObservableObject). You don't have to start from scratch: our rules category lists ready-made AGENTS.md files and rule packs for Swift. To check what Codex loaded, run codex --ask-for-approval never "Summarize the current instructions." from the repo root (OpenAI).

3. Connect Xcode's built-in tools

Xcode ships an MCP server for external agents. In Xcode, open Settings › Intelligence and, under Model Context Protocol, turn on "Allow external agents to use Xcode tools". Then register it in Codex:

codex mcp add xcode -- xcrun mcpbridge
codex mcp list

Open your project in Xcode before prompting; Xcode shows an alert when the agent connects (Apple). Cursor's documentation describes the same bridge as available from Xcode 26.3 (Cursor). Catalog entry: Xcode MCP servers.

If you also run Codex inside Xcode (Xcode Settings › Intelligence › OpenAI), note that MobileBuildMCP's docs say Xcode's Codex agent currently only supports a project-scoped .codex/config.toml and starts with a minimal PATH (MobileBuildMCP).

4. Add MobileBuildMCP for simulators, screenshots and UI

OpenAI's page recommends XcodeBuildMCP once "schemes, targets, simulator control, screenshots, logs, and UI interaction matter" (OpenAI). That project is now called MobileBuildMCP; see our XcodeBuildMCP setup guide for the rename. Its documented Codex setup:

codex mcp add MobileBuildMCP -- npx -y mobilebuildmcp@latest mcp

or in ~/.codex/config.toml:

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

The timeout matters: if you see timed out awaiting tools/call after 60s, set tool_timeout_sec inside the server block. Codex ignores a top-level tool_timeout_sec for MCP tool calls (MobileBuildMCP). Only the simulator workflow is on by default; enable more in the project config.

Need the agent to see and tap the UI with a different tool? Compare options in iOS Simulator MCP servers.

5. Add SwiftUI skills when the work gets specialized

A Codex skill is a folder with a SKILL.md (required name and description) plus optional scripts and references. Codex starts with each skill's name and description and loads the full instructions only when it picks the skill. You can invoke one explicitly with /skills or by typing $ in the CLI or IDE extension (OpenAI).

Where Codex looks for local skills (OpenAI):

Many Swift skills install with npx skills add <owner>/<repo>. Some READMEs still say to copy folders into $CODEX_HOME/skills; if a skill doesn't show up, check the locations above and restart Codex.

OpenAI's iOS page names a set of skills; these are the matching entries in our catalog:

(Mapping by name and description; OpenAI's page does not link repositories, so verify before relying on it.) For tests, add Swift Testing Pro. More in SwiftUI agent skills.

6. Ship from the terminal

OpenAI's stack table lists an App Store Connect CLI for distribution (OpenAI). Options in our catalog: App Store Connect CLI skills, asc-cli and MCP servers in App Store Connect MCP.

Recommended setup at a glance