iOS 26 / Swift 6.2 AGENTS.md for Codex

Stack rules — iOS

Swift 6.2, strict concurrency, SwiftUI, min iOS 26, Xcode 26.

• iOS 26 APIs only. No #available, no UIKit fallbacks.
• @Observable @MainActor final class view models; views are layout only; VMs never import SwiftUI.
• guard, optional chaining, do/catch. No !, no try!.
• NavigationStack + navigationDestination; .sheet(item:); Map(position:).
• TabView { Tab } + .tabBarMinimizeBehavior(.onScrollDown); search = Tab(role: .search).
• .glassEffect() / GlassEffectContainer for floating controls. Never hand-style toolbars or tab bars.
• @Animatable for custom animation; .backgroundExtensionEffect() for hero media; WebView(url:) not WKWebView.
• Shared state via @Environment, no singletons in views. Every view has #Preview with mocks.
• Layout: Features//{Views,ViewModels,Models}, Core/ services behind protocols, mocks share the protocols.
• Tests: Swift Testing. Unit = view models and decoding with JSON fixtures. UI = one happy path per feature.
• Build: xcodebuild -scheme -destination 'generic/platform=iOS' build
• 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

AGENTS.md

Project

• App:
• Stack: , ,
• Entry: →
• 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.

What is this?

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:

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:

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

That's it

• Steps 1, 2 and 6 work for any project.
• Steps 3, 4 and 5 are only for iPhone/Mac apps.
• Repeat only Step 2 for each new project.

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

2) Set session defaults

• Call mcp__XcodeBuildMCP__session-set-defaults with:
  • projectPath or workspacePath (whichever the repo uses)
  • scheme for the current app
  • simulatorId from the booted device
  • Optional: configuration: "Debug", useLatestOS: true

3) Build + run (when requested)

• Call mcp__XcodeBuildMCP__build_run_sim.
• 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:
  1. mcp__XcodeBuildMCP__get_sim_app_path
  2. 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.