# iOS 26 / Swift 6.2 AGENTS.md for Codex > Source: > Published: 2026-11-05 21:55:28+00:00 Test: xcodebuild test -scheme -destination 'platform=iOS Simulator,name=' Tooling (Codex) Skills (Paul Hudson, MIT): swiftui-pro, swift-concurrency-pro, swift-testing-pro, swiftdata-pro. Use swiftui-pro to review every SwiftUI change before committing. Install once: for r in SwiftUI Swift-Concurrency Swift-Testing SwiftData; do d=$(mktemp -d); git clone -q https://github.com/twostraws/$r-Agent-Skill $d && cp -R $d/*-pro ~/.codex/skills/; done XcodeBuildMCP for build, simulator, screenshots, and UI taps instead of raw xcodebuild when available. Use the ios-debugger-agent skill to drive it. Install once: codex mcp add XcodeBuildMCP -- npx -y xcodebuildmcp@latest mcp && mkdir -p ~/.codex/skills/ios-debugger-agent && curl -sL https://gist.githubusercontent.com/NicolasR27/21e1040cbb4e800f494247d23eddc765/raw/xcode-mcp-skill.md -o ~/.codex/skills/ios-debugger-agent/SKILL.md Source: https://github.com/cameroncooke/XcodeBuildMCP Folders: /, /, /, / Build: 2>&1 | tail -20 Test: 2>&1 | tail -20 Secrets: , never committed Features — — live|beta|flagged Decisions Changelog (newest first, trim >30 days) YYYY-MM-DD feat: () Code Follow the existing style, names, and folder layout. Match the stack rules below. No force-unwraps, no swallowed errors, no TODOs left behind. Logic lives outside UI. UI stays thin and previewable/testable. New code gets a unit test. Fixtures over network calls in tests. Stack rules First run If any <...> placeholder remains, inspect the repo, fill every section from what you find, delete this section, and commit chore: fill AGENTS.md before starting the task. Work Edit only what the task needs. No reformatting. Ask before adding a dependency. Reply with the diff only. Small task (one file, rename, typo, copy change, obvious fix): no exploring, no plan, no skills, no tests run. Open the file, edit, build, commit. Under 5 tool calls. Read only the files you touch. Use grep -n, never dump whole files or directories. Do not re-read a file after editing it. Do not repeat the build output back. Run the build and test commands above. Fix failures; never return broken code. Then add a Changelog line (and Features line if new), and commit: git add -A && git commit -m ": ". Do not push. Setup Any repo: curl -sL https://gist.githubusercontent.com/NicolasR27/21e1040cbb4e800f494247d23eddc765/raw/AGENTS.md -o AGENTS.md iOS: also curl -sL https://gist.githubusercontent.com/NicolasR27/21e1040cbb4e800f494247d23eddc765/raw/AGENTS.ios.md >> AGENTS.md Per-folder AGENTS.md overrides root. Global defaults: ~/.codex/AGENTS.md. A starter kit that makes Codex a better coding helper for any project, with extras for iPhone apps. The problem. Every time you open Codex, it forgets everything about your project. It wastes tokens re-reading your code, guesses your style, uses old Apple APIs, and writes long replies you don't need. What each file does: File What it does Why it helps AGENTS.md A rules sheet Codex reads at the start of every chat. It holds your app's features, decisions, and recent changes, plus how to work. Codex remembers your project between chats, stops re-reading everything, sends short diffs, and commits its own work. AGENTS.ios.md Extra rules for iPhone apps: iOS 26 APIs, SwiftUI patterns, Swift Testing. Codex writes modern Swift instead of old code from tutorials. Paul Hudson skills Expert checklists for SwiftUI, concurrency, testing, and SwiftData. Catches mistakes and outdated code before you commit. xcode-mcp-skill.md + XcodeBuildMCP Lets Codex build your app, open the simulator, tap buttons, take screenshots, and read logs. Codex checks its own work in the real app instead of asking you to. It keeps itself updated. On the first task, Codex fills in the blanks about your project. After each task it adds a line to the changelog, so the next chat already knows what changed. Setup in 6 steps You only do this once. Open the Terminal app on your Mac (press Cmd+Space, type Terminal, hit Enter). Copy each gray box, paste it into Terminal, press Enter. Step 1. Get Codex Go to https://chatgpt.com/codex and download the Codex app. Open it and sign in with your ChatGPT login. Step 2. Put the rules file in your project This file tells Codex how to behave in your project. First, go to your project folder. Type cd (with a space), then drag your project folder from Finder into Terminal, and press Enter. Then paste this: ``` curl -sL https://gist.githubusercontent.com/NicolasR27/21e1040cbb4e800f494247d23eddc765/raw/AGENTS.md -o AGENTS.md ``` Making an iPhone app? Also paste this: ``` curl -sL https://gist.githubusercontent.com/NicolasR27/21e1040cbb4e800f494247d23eddc765/raw/AGENTS.ios.md >> AGENTS.md ``` Done. Open the project in Codex and give it any task. The first time, Codex fills in the blanks in the file by itself. Step 3. Add the Swift skills (iPhone apps only) Skills are extra knowledge packs. These are from Paul Hudson (Hacking with Swift). Paste this whole thing: ``` mkdir -p ~/.codex/skills for r in SwiftUI Swift-Concurrency Swift-Testing SwiftData; do d=$(mktemp -d); git clone -q https://github.com/twostraws/$r-Agent-Skill $d && cp -R $d/*-pro ~/.codex/skills/ done ``` Quit and reopen the Codex app. You will see them under Settings → Skills. Step 4. Let Codex use Xcode (iPhone apps only) This lets Codex build your app, run the simulator, and take screenshots. Paste: ``` codex mcp add XcodeBuildMCP -- npx -y xcodebuildmcp@latest mcp mkdir -p ~/.codex/skills/ios-debugger-agent curl -sL https://gist.githubusercontent.com/NicolasR27/21e1040cbb4e800f494247d23eddc765/raw/xcode-mcp-skill.md -o ~/.codex/skills/ios-debugger-agent/SKILL.md ``` The first line adds the Xcode tool. The next two add a skill that teaches Codex how to use it (build, run, tap, read logs). Quit and reopen Codex. Check Settings → MCP servers. You need Xcode installed already. If it says codex: command not found, install the command line tool first: ``` npm i -g @openai/codex ``` Step 5. How to use the skills You do not have to do anything special. Codex reads the skill descriptions and picks one when your request matches. You can also call one by name. Two keys to remember in the Codex chat box: Type /skills and press Enter to see every skill you installed and turn them on or off. Type $ to pick a skill and use it. A list pops up. Pick one with the arrow keys, press Enter, then type what you want. Examples: You type What happens $swiftui-pro review my changes Checks your SwiftUI for old APIs, bad patterns, slow views $swift-concurrency-pro fix the warnings in LoginView Fixes async/await, @MainActor, Sendable errors $swift-testing-pro write tests for CartViewModel Writes Swift Testing tests $swiftdata-pro review my models Checks SwiftData models and queries $ios-debugger-agent run the app and screenshot the home tab Builds, launches the simulator, taps around, takes screenshots, reads logs Plain English works too. "Run the app in the simulator and check the login screen" triggers the debugger skill on its own. Tip: skills add text to every request that uses them. Call them when you need them, not on every message. Step 6. Faster replies Paste this so Codex thinks less hard by default (faster, uses less of your limit): ``` mkdir -p ~/.codex && echo 'model_reasoning_effort = "low"' >> ~/.codex/config.toml ``` When a task is tough, just tell Codex "think harder on this one". Use XcodeBuildMCP to build, run, launch, and debug the current iOS project on a booted simulator. Trigger when asked to run an iOS app, interact with the simulator UI, inspect on-screen state, capture logs/console output, or diagnose runtime behavior using XcodeBuildMCP tools. iOS Debugger Agent Overview Use XcodeBuildMCP to build and run the current project scheme on a booted iOS simulator, interact with the UI, and capture logs. Prefer the MCP tools for simulator control, logs, and view inspection. Core Workflow Follow this sequence unless the user asks for a narrower action. 1) Discover the booted simulator Call mcp__XcodeBuildMCP__list_sims and select the simulator with state Booted. If none are booted, ask the user to boot one (do not boot automatically unless asked). If the build fails, check the error output and retry (optionally with preferXcodebuild: true) or escalate to the user before attempting any UI interaction. After a successful build, verify the app launched by calling mcp__XcodeBuildMCP__describe_ui or mcp__XcodeBuildMCP__screenshot before proceeding to UI interaction. If the app is already built and only launch is requested, use mcp__XcodeBuildMCP__launch_app_sim. If bundle id is unknown: mcp__XcodeBuildMCP__get_sim_app_path mcp__XcodeBuildMCP__get_app_bundle_id UI Interaction & Debugging Use these when asked to inspect or interact with the running app. Describe UI: mcp__XcodeBuildMCP__describe_ui before tapping or swiping. Tap: mcp__XcodeBuildMCP__tap (prefer id or label; use coordinates only if needed). Type: mcp__XcodeBuildMCP__type_text after focusing a field. Gestures: mcp__XcodeBuildMCP__gesture for common scrolls and edge swipes. Screenshot: mcp__XcodeBuildMCP__screenshot for visual confirmation. Logs & Console Output Start logs: mcp__XcodeBuildMCP__start_sim_log_cap with the app bundle id. Stop logs: mcp__XcodeBuildMCP__stop_sim_log_cap and summarize important lines. For console output, set captureConsole: true and relaunch if required. Troubleshooting If build fails, ask whether to retry with preferXcodebuild: true. If the wrong app launches, confirm the scheme and bundle id. If UI elements are not hittable, re-run describe_ui after layout changes.