Codex Swift and iOS: a practical guide for developers

Codex is a practical coding agent for Swift and iOS projects when you run codex from the repository root, keep an AGENTS.md that describes Xcode and Swift Package Manager commands, and work in small increments that you can verify with XCTest. This guide covers setup, prompts, pitfalls, and verification for SwiftUI, UIKit, SPM, async/await, and Xcode projects. If you are new to the command line workflow, see How to use Codex CLI: a step-by-step guide.

How Codex fits Swift and iOS projects

Swift and iOS development rewards an agent that can read many files, understand compiler diagnostics, and run build and test commands. Codex fits because it operates in a terminal where xcodebuild, swift build, swift test, and swiftlint are first-class commands. It can navigate a modular SPM layout, follow SwiftUI view composition, edit UIKit view controllers, and reason about async/await, @MainActor, and Sendable. When a build fails, Codex can read the exact error from xcodebuild and make a targeted fix rather than guessing. This is especially useful in Swift because many issues are caught at compile time, and the compiler gives detailed diagnostics that the agent can use immediately. When work spans several modules or agents, the pattern in AI agent workflow: teams, parallel parts and flows helps keep changes isolated.

Configuring the project for Codex

Codex reads project instructions from AGENTS.md. Put one in the repository root or the folder where you invoke codex. For a Swift and iOS project, the file should give build and test commands, folder conventions, and rules about Xcode-managed files. Keep it short enough to be read every run; a wall of text dilutes the important instructions. The Codex agent reads AGENTS.md from the project root, so keep it focused.

# AGENTS.md

## Build and test
- Package: `swift build && swift test`
- Xcode: `xcodebuild -project MyApp.xcodeproj -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 15' test`
- Lint: `swiftlint --strict`

## Layout
- Put feature code in `Sources/Features/<FeatureName>/`.
- Put SwiftUI views in `Sources/Features/<FeatureName>/Views/`.
- Put UIKit view controllers in `Sources/Features/<FeatureName>/ViewControllers/`.
- Put tests in `Tests/<FeatureName>Tests/`.

## Rules
- Do not edit `MyApp.xcodeproj/project.pbxproj` unless the task explicitly asks for target changes. Prefer SPM package changes.
- Keep model and service types `Sendable`; mark view models and view controllers `@MainActor`.
- Use `async`/`await` instead of completion handlers unless you are working with an API that requires callbacks.
- Never modify `DerivedData`, `*.xcuserstate`, or signing files.
- Run `swift test` or the Xcode test command after every code change.

This gives Codex the commands it needs to verify work and stops it from touching files that are hard to review. Replace the scheme name and simulator destination with the ones in your project.

A practical working loop and prompts

Work in a loop: start clean, ask Codex to inspect the relevant files, make one small change, run the tests, then review the diff with git diff. Do not ask for a broad rewrite in one turn; Swift compiler feedback is most useful when changes are small enough to attribute errors. After the agent edits code, run the test command yourself once before you trust the result. The prompts below work as a starting point for typical Swift and iOS tasks.

• Read Models/Item.swift and ItemStore.swift, then add an in-memory ItemStore with async CRUD methods and XCTest coverage. Do not edit the .xcodeproj; use existing SPM targets.
• Refactor HomeView from a single large SwiftUI body into smaller private subviews in the same file. Keep the public interface unchanged and run swift build after the change.
• Add pull-to-refresh to ItemsViewController using UIRefreshControl. Keep the existing data source methods, do not modify the storyboard, and add a unit test if the refresh logic can be isolated.
• Fix the concurrency warning in CartViewModel: make the class @MainActor and mark the network client as Sendable. Run swift test and show the diff.
• Add XCTest cases for OrderValidator covering an empty order, an invalid coupon, and a successful order. Keep the tests deterministic and fast.

After each prompt, ask Codex to run the build or test command and paste the relevant error if it fails. This keeps the loop tight.

Strengths and pitfalls for Swift and iOS

Codex handles additive feature work, unit tests, SPM manifest edits, async/await conversions, and refactoring SwiftUI view hierarchies well. It can write a new ObservableObject or @Observable model, add mock services for tests, and split large views. It is also good at reading xcodebuild output and applying a focused fix.

Watch it closely on Xcode project internals, signing and entitlements, generated Core Data files, storyboards and xibs, and anything in Info.plist that affects permissions. A small change to project.pbxproj can introduce duplicate target membership or break build phases. The table shows the files that deserve manual review.

Also watch for Swift-specific concurrency pitfalls: a fix may compile in Swift 5 language mode but fail under strict concurrency, or it may require iOS 17 APIs without availability checks. Ask the agent to add @available checks when it uses newer APIs.

How to test and verify the changes

Testing is the core of the loop. Always have a baseline of swift test or xcodebuild test before asking Codex to change logic. For a pure SPM module, swift test is faster and gives clean output. For an app target, use xcodebuild test with a simulator destination; if the agent suggests swift test for an .xcodeproj, remind it to use the Xcode command. Have Codex add tests alongside the change, not after. When a test fails, paste the failure message back to Codex and ask for a minimal fix. If the change is large, run a second review pass with AI code review: check what your agents write before merging.

Running multiple Codex agents with AgentVera

When you need more than one Codex agent on a Swift and iOS project, AgentVera helps: each agent can work in its own git worktree, so changes don’t overwrite each other. Automatic code review after each turn flags Swift-specific issues and links to file:line, which helps catch actor isolation or target membership mistakes. Checkpoints let you undo a bad turn and replay it, and token budgets stop a runaway agent without losing its conversation.

Wrap-up

Codex can be a reliable partner for Swift and iOS work if you give it clear build commands and module boundaries in AGENTS.md, keep changes small and testable, and review Xcode-managed files yourself. Start with one small feature, run XCTest before and after, and expand from there.