iOS 26 / Swift 6.2 AGENTS.md for Codex

A developer published a starter kit of AGENTS.md and AGENTS.ios.md configuration files that give OpenAI's Codex coding agent persistent project context, alongside optional Paul Hudson SwiftUI/concurrency/testing/SwiftData skills and an XcodeBuildMCP integration for building, running simulators, tapping UI, and capturing screenshots. The setup aims to cut token waste from re-reading code, enforce modern iOS 26 and Swift 6.2 patterns, and let the agent verify its own changes in a running app.

Test: xcodebuild test -scheme <Scheme -destination 'platform=iOS Simulator,name=<Sim ' 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: <src /, <features /, <core or shared /, <tests / Build: <build command 2 &1 | tail -20 Test: <test command 2 &1 | tail -20 Secrets: <file , never committed Features — <path — live|beta|flagged Decisions <Rule an agent would otherwise undo, e.g. keep REST not GraphQL, no new dependencies Changelog newest first, trim 30 days YYYY-MM-DD feat: <path 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 <paste the stack file here, or leave empty 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 "<feat|fix|refactor|test|chore : <what ". 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.