# Codex Swift and iOS: a practical guide for developers

URL: https://agentvera.dev/en/blog/codex-for-swift/ · Published: 2026-11-01

Learn to run Codex on Swift and iOS projects: set up AGENTS.md, write SwiftUI and UIKit prompts, verify with XCTest, and avoid Xcode project pitfalls.

**In short:**

- Run Codex from the repo root and put Xcode build, test, and lint commands in AGENTS.md so it works with Swift Package Manager and .xcodeproj projects.
- Use small, testable changes and ask the agent to run XCTest after each edit, especially for async/await, actor isolation, and Sendable conformance.
- Review project.pbxproj, Info.plist, and signing files manually; keep Codex out of generated or Xcode-managed files unless you diff each change.

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](/en/blog/how-to-use-codex-cli/).

## 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](/en/blog/ai-agent-workflow-pipeline/) 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](/en/agents/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.

| File or area | What to watch |
|---|---|
| `MyApp.xcodeproj/project.pbxproj` | Duplicate file references, target membership, build settings |
| `Info.plist` and `.entitlements` | Missing usage descriptions, signing, capabilities |
| `*.xcdatamodeld` | Model codegen, migration, entity attributes |
| SwiftUI preview providers | Preview-only assumptions, simulator-only APIs |

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](/en/blog/ai-code-review/) 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.

## Frequently asked questions

**Can Codex edit an existing Xcode project directly?** Yes, it can read and change Swift files, but keep project.pbxproj changes under review. Tell Codex in AGENTS.md to prefer Swift Package Manager targets or folder references and to avoid modifying the .xcodeproj unless explicitly asked.

**Does Codex support Swift Package Manager and XCTest?** Yes. Codex runs swift build and swift test in a terminal, so it can add SPM targets and write XCTest cases. Put the package layout and test commands in AGENTS.md so it uses the right commands.

**How do I stop Codex from breaking my iOS signing or entitlements?** Exclude .entitlements, provisioning profiles, and signing-related build settings from agent edits. Add a rule in AGENTS.md that says not to modify signing files and to leave signing style and team settings alone.

**What should I put in AGENTS.md for Swift concurrency?** Include rules such as keep model and service types Sendable, mark view models and view controllers @MainActor, and use async/await instead of callbacks. This helps Codex produce changes that pass strict concurrency checks.

---

**About AgentVera.** AgentVera is a desktop app for macOS, Windows and Linux, built by Solviera Teknoloji. It runs 18 AI coding agents (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) side by side, per project, in real terminals with the user's own CLI installs and logins. The free plan has unlimited agents. Download: https://agentvera.dev/en/download/ · Pricing: https://agentvera.dev/en/pricing/