AGENTS.md for Mobile Projects: Setting Up Codex for iOS and Android
Short answer: AGENTS.md is the instruction file OpenAI Codex reads before working in a repository. For mobile projects it should state how to build and test each platform, which files are off limits, how versions and signing work and what counts as done. A good AGENTS.md turns Codex from a guess-and-check assistant into a predictable contributor for iOS and Android code.
On this page
What should an AGENTS.md contain for a mobile project?
Codex reads AGENTS.md files from the repository root and from subdirectories, with more specific files applying to their folder. For a web project, a few lines about the test command often suffice. Mobile projects need more, because the agent cannot open Xcode, tap a simulator or inspect a device log unless you tell it how to approximate those steps from the command line.
At minimum, cover five areas: project layout, build and test commands per platform, coding conventions, protected files and the definition of done. Keep it short enough that a human would read it too. Two pages of precise rules beat ten pages of aspirations.
A practical structure
- Overview: one paragraph on what the app does, the stack (for example Swift with SwiftUI, Kotlin with Jetpack Compose, React Native or Flutter) and minimum OS versions.
- Layout: where shared code, iOS code, Android code, assets and tests live.
- Commands: exact commands to install dependencies, run unit tests, lint, and produce a debug build for each platform.
- Conventions: architecture pattern, state management, naming, localization rules, accessibility requirements.
- Do not touch: signing configs, provisioning files,
Info.plistprivacy keys and Gradle signing blocks unless the task explicitly says so. - Definition of done: tests pass, lint is clean, no new warnings, new strings are localized, screenshots or test output attached to the pull request.
Platform commands Codex can actually run
The Codex cloud environment is a Linux container. That works well for Android: Gradle tasks such as unit tests and lint run headless, and you can name them explicitly, for example ./gradlew testDebugUnitTest lintDebug. For iOS, compilation requires macOS, so in the cloud the agent cannot build the Xcode project. Be explicit about that in AGENTS.md so Codex does not waste time trying.
Practical workarounds: keep business logic in a Swift package or Kotlin Multiplatform module that has tests runnable on Linux, run iOS builds in CI on macOS runners and instruct Codex to rely on CI results for iOS changes. When teams use the Codex CLI locally on a Mac, a separate section can list xcodebuild commands for test schemes and simulators.
For React Native and Flutter projects, separate JavaScript or Dart checks, which run anywhere, from native builds, which need the right toolchain. State which checks are mandatory for each kind of change.
Need a hand? neooutput helps with exactly this. Book a call for free and get a clear plan in 15 to 30 minutes.
Guardrails that prevent costly mistakes
Mobile repositories contain files where a small, plausible-looking edit causes a store rejection or a broken release. Write these rules in plain imperative sentences:
- Never change bundle identifiers, application IDs, team IDs or signing settings.
- Never add a permission or privacy usage string without a task that requires it; when you add one, explain the user-facing reason in the pull request.
- Never add a third-party SDK without listing what data it collects, so privacy labels and the data safety form can be updated.
- Never commit API keys, keystores, certificates or service account files.
- Increment build numbers only in release tasks, following the documented scheme.
- Keep UI text in localization files, never hard-coded in views.
Nested AGENTS.md files for monorepos
If the repository holds a backend, a web app and mobile apps, use a short root file for shared rules and put platform specifics into ios/AGENTS.md, android/AGENTS.md and similar. Codex applies the closest file, so a task inside the Android folder sees Android rules without being distracted by iOS details.
A short example of a useful rule set for an Android module might read: run ./gradlew :app:testDebugUnitTest before finishing, use Compose for all new screens, place strings in res/values/strings.xml with translations for every supported locale, and never modify app/build.gradle signing blocks. Four lines like these prevent most of the corrections reviewers would otherwise repeat on every pull request.
Review AGENTS.md like code. When Codex repeatedly makes the same mistake, add one precise rule rather than a vague warning. When a rule no longer applies, delete it, since stale instructions are worse than none.
Training the team, not just the agent
The teams that benefit most from Codex on mobile projects treat agent instructions as a shared engineering practice. neooutput runs workshops, trainings and 1:1 consulting on agentic coding with Claude Code, OpenAI Codex and Cursor, remote or on-site, in English and German. A typical session works on your real repository: drafting AGENTS.md, setting up CI so iOS changes get verified on macOS runners and defining review rules for agent pull requests.
Where a team wants hands-on delivery rather than training, apprat.io provides coding agents plus senior AI Code Engineers who review every change and test on real devices before App Store and Google Play publication. neooutput also offers a free 15-minute call to find the right format.
Frequently asked questions
Can OpenAI Codex build iOS apps in the cloud?
The Codex cloud environment runs Linux, so it cannot compile Xcode projects directly. It can still edit Swift code, run tests for logic that compiles on Linux and open pull requests. Use CI with macOS runners to build and test iOS changes, or run the Codex CLI locally on a Mac with xcodebuild commands listed in AGENTS.md.
Is AGENTS.md the same as CLAUDE.md?
They serve the same purpose for different agents. Codex reads AGENTS.md, while Claude Code reads CLAUDE.md. Many teams keep one source of truth and reference or mirror it in the other file so both agents follow identical build commands, conventions and guardrails. Keep them in sync whenever rules change.
How long should an AGENTS.md file be?
Long enough to be precise, short enough to be read. For most mobile projects, one to two pages in the root plus short platform files is enough. Prefer exact commands and concrete rules over general advice, and remove outdated instructions promptly so the agent does not follow rules that no longer apply.
Should Codex be allowed to edit Info.plist or Gradle files?
Yes, but only when the task requires it and with explicit review. These files control permissions, signing and build behavior, so a wrong change can cause crashes or rejections. State in AGENTS.md which keys are protected and require the agent to explain every change to these files in its pull request description.
