Codex React Native: a practical guide for coding agents

Codex is most useful in a React Native repo when you treat it as an engineer who can read the whole project, run Metro, edit TypeScript, and write tests, but still needs clear boundaries. Start Codex in the project folder, point it at small changes, and verify every change on a simulator or device before merging.

Why Codex suits React Native work

React Native projects mix JavaScript, TypeScript, JSX, native projects, and Metro-specific errors. Codex handles that mix well because it can read component trees, navigation config, app.json, and test files in one session. It can run npx expo start, read Metro’s output, and adjust TypeScript or Babel config when a new dependency needs it. That makes it useful for navigation refactors, theme migration, hook testing, and native build troubleshooting.

The agent is not limited to isolated snippets. It can follow a stack trace from a red screen back to the component, propose a fix, run the test suite, and show the diff. On a React Native codebase this is valuable because many errors only appear after Metro recompiles or after a native module is linked.

Setting up the project for Codex

The most important step is to put a concise AGENTS.md in the repo root. Codex reads project instructions from AGENTS.md, so this file should describe commands, folder conventions, and React Native-specific rules. Keep it short enough to be read every session but specific enough to prevent bad assumptions.

Example AGENTS.md for an Expo Router project:

# AGENTS.md

## Commands
- Install: `npm install`
- Start Metro: `npx expo start`
- Run on Android emulator: `npx expo run:android`
- Run on iOS simulator: `npx expo run:ios`
- Typecheck: `npx tsc --noEmit`
- Lint: `npm run lint`
- Test: `npm test -- --watchAll=false`
- Build production bundle: `npx expo export`

## Folder conventions
- `/app` contains Expo Router screens; file names define routes.
- `/components` holds reusable UI; keep components presentational where possible.
- `/lib` contains utilities, API clients, and hooks.
- `/theme` contains colors, spacing, and typography tokens.

## React Native rules
- Use TypeScript for all new files; do not introduce `any` without a comment.
- Use React Navigation or Expo Router; do not mix navigation patterns.
- Keep native projects `/ios` and `/android` as generated; do not edit them unless a task requires native code.
- Prefer platform-specific files (`Button.ios.tsx`, `Button.android.tsx`) over inline `Platform.OS` when logic differs.
- Do not commit secrets or local environment files.

If you have a bare workflow instead of Expo, replace the Expo commands with npx react-native run-android and run-ios, and add the pod install command for iOS. The principle is the same: give the agent the exact commands you already run locally. For the CLI basics, see How to use Codex CLI: a step-by-step guide.

A working loop for React Native tasks

Use a tight loop: plan the change, let Codex implement a small slice, run the typechecker and tests, then review the diff. Avoid asking for a large feature in one prompt. Metro and native rebuilds are slow, so smaller changes are easier to bisect when something breaks.

Start codex in the project folder and ask for one concrete change at a time. The agent should produce a diff, run any commands you specified in AGENTS.md, and report what it verified. Then you verify on a simulator or device.

Example prompts that work well:

• Fix the TypeScript errors in src/screens/ProfileScreen.tsx without changing the component's public API.
• Add a login screen using React Navigation and wire it to the existing auth context in src/context/AuthContext.tsx.
• Write a Jest test for the useFetchUser hook with mocked fetch and React Native's act.
• Replace the inline styles in src/components/ProductCard.tsx with the theme tokens from src/theme.
• Update the Android build config so the app name matches app.json.

These prompts give a file or area, a behavior, and a constraint. That reduces the chance the agent rewrites unrelated code or introduces a second navigation pattern.

Where Codex excels and where to watch closely

Codex is strong at mechanical, well-scoped work: migrating styles to a theme, updating screens after a navigation rename, adding tests for pure logic, and fixing Metro bundling errors. It is also good at reading native build errors and suggesting dependency fixes, but native changes need extra review.

Pay particular attention to any change inside /ios or /android. The agent may know the syntax of Gradle or Xcode projects but not the side effects of adding a permission, a pod, or a custom build phase. Always rebuild the native app after such changes.

Testing and verification with Codex

Do not rely on the agent’s summary that everything works. Ask it to run the exact commands from AGENTS.md and paste the output. For React Native, the minimum verification is:

• npx tsc --noEmit for type errors.
• npm run lint for code style and hooks rules.
• npm test -- --watchAll=false for unit and component tests.
• npx expo export or a debug build to catch Metro bundling errors.

For UI changes, launch the app on a simulator or device after the agent finishes. Codex cannot see the rendered UI, so layout regressions, touch target issues, and platform-specific styling must be checked by a human. If the agent generated a test, read the assertions to make sure they match the intended behavior, not just that the test passes.

For a deeper look at how to check agent-written code, see AI code review: check what your agents write.

Running several agents on one React Native project with AgentVera

AgentVera is a desktop app that runs coding agents’ real command line tools side by side in one window, each in its own real terminal panel. For React Native work, parallel git worktrees are the key benefit: one agent can refactor navigation while another writes tests without overwriting the same files. Automatic code review catches unsafe native config changes and broken style tokens when an agent’s turn ends. Checkpoints let you roll back a failed Metro or native build step in one click, and token budgets stop a long debugging session from consuming the whole account. These controls matter because React Native changes often touch many files and require repeated simulator verification.

Wrap-up

Codex fits into a React Native workflow when you give it a precise AGENTS.md, keep prompts scoped to one file or one behavior, and verify with Metro, Jest, and a real device. Treat native project changes as high-risk and review them manually. With that discipline, Codex becomes a reliable pair engineer for navigation, theming, tests, and build troubleshooting, rather than a source of mysterious diffs.