Codex CLI With Xcode: Build, Test, and Review Changes

Codex CLI works against any repository it can read and any build tool it can run from a shell. That includes Xcode projects. You point it at a repository containing an .xcodeproj or .xcworkspace file, describe the change you want, and let it use xcodebuild to confirm the build still compiles.

What the CLI cannot do is open the Xcode IDE or use Interface Builder. It works at the code level: Swift and Objective-C files, plists, asset catalogs, and the build system. Tools like fenbs keep app requirements, design decisions, and unresolved build work in one place so each session knows what the current constraints are before making changes.

What Codex CLI can and cannot do in an Xcode project

• Can do: read and edit Swift, Objective-C, and supporting files; run xcodebuild commands to compile and test; read build output to diagnose errors; make changes across multiple files in a single session.
• Cannot do: open the Xcode IDE; edit storyboard or xib files visually; use the Simulator GUI; sign or notarize a build; manage certificates or provisioning profiles directly.

For tasks that live entirely in code, the CLI is effective. For tasks that require visual layout changes or Xcode-specific project configuration, you will get better results doing that part in Xcode and then using the CLI for the code that follows.

Repository setup

Codex CLI reads AGENTS.md files in the repository to understand the project before it acts. Add one to your Xcode project root with a short description of the app, the target iOS or macOS version, and any conventions the codebase follows. This reduces incorrect assumptions at the start of a session.

Include the build command the agent should use for verification. For example:

## Build
xcodebuild -scheme MyApp -destination "generic/platform=iOS" build

## Test
xcodebuild test -scheme MyApp -destination "platform=iOS Simulator,name=iPhone 16"

If the project uses Swift Package Manager for dependencies, make sure the packages are resolved before the first agent run. An unresolved package causes a build failure that looks like a code error and sends the agent down a wrong path.

Running builds with xcodebuild

Ask the agent to run xcodebuild after making changes to confirm the project still compiles. A short build check is faster than a full test run and catches most obvious errors. Use the -quiet flag to reduce output when all you need is a pass or fail:

xcodebuild -scheme MyApp -destination "generic/platform=iOS" build -quiet

Build output from xcodebuild is verbose by default. Pipe it through xcbeautify or xcpretty if you want cleaner output for the agent to read. Both are open-source tools available through Homebrew.

Running tests from the terminal

Unit tests can run from the terminal with xcodebuild test. UI tests require a running simulator, which adds setup time. For a quick feedback loop during agent-assisted coding, focus the agent on unit test targets and leave UI test runs for manual verification.

Specify the destination explicitly to avoid ambiguity. A missing or wrong destination is one of the most common causes of a confusing test error when running xcodebuild in a script:

xcodebuild test -scheme MyAppTests -destination "platform=iOS Simulator,name=iPhone 16" -quiet

Reviewing changes before committing

After the agent finishes a session, review the diff before committing. Codex CLI can produce correct-looking changes that misunderstand a design decision from an earlier discussion. A quick git diff shows the scope before anything is committed.

Pay particular attention to changes in the .xcodeproj directory. The project file format is not human-readable, but build setting or target membership changes show up here and can affect which files get compiled. If the agent changed the project file unexpectedly, review it carefully or revert that part while keeping the code changes.

What to do when xcodebuild reports unexpected errors

Build errors are not always caused by the last change the agent made. A stale derived data folder is a common source of confusion. If the build fails with errors that do not correspond to any code the agent touched, clean the build folder first by running xcodebuild clean before the next build attempt. The agent can do this itself if you include it in the verification instructions in AGENTS.md.

Code signing errors appear frequently in environments without valid development certificates. The agent cannot resolve a signing failure through code changes. Switch the build destination to a simulator rather than a device and add CODE_SIGNING_ALLOWED=NO to the xcodebuild invocation for local verification runs to separate signing problems from build problems.

How to do this with fenbs

1. Create a free account and add the app as a project in fenbs.
2. Add the active features as tasks and any agreed design decisions as Decisions. Include the target platform and any constraints the agent must respect.
3. Before each Codex CLI session, check the fenbs context so the agent starts from the current requirements rather than assumptions.
4. After a session, record what changed, what was tested, and any unresolved build issues as task comments or a Where we left off update.
5. Connect Codex CLI to fenbs over MCP from Integrations to let the agent read and update the project record directly.

For a broader introduction to using Codex CLI in a macOS environment, see the Codex CLI best practices guide. For questions about harness options such as running computer-use tasks, see Codex CLI computer use.