# Codex React Native: a practical guide for coding agents

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

Learn how to use Codex in a React Native project: set up AGENTS.md, run Expo and Jest, review diffs, and avoid native build and Metro pitfalls.

**In short:**

- Set up a concise AGENTS.md so Codex knows Expo or bare workflow commands and React Native rules.
- Use small, scoped prompts and always verify with typecheck, Jest, and a simulator or device.
- Treat native project changes as high-risk and use parallel worktrees and code review for multi-agent work.

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](/en/agents/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:

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

## 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.

| Task | What Codex does well | Watch closely |
|------|----------------------|---------------|
| Navigation refactor | Updates stack/tab config and imports consistently | It may rename route names incorrectly or miss deep link config |
| Styling and theme migration | Replaces hard-coded colors and spacing with tokens | Token values may differ, changing the visual result |
| Jest tests | Generates render/act tests and mocks | Tests may pass without asserting useful behavior or may hide async `act` warnings |
| Native config changes | Edits `app.json`, `Info.plist`, or `build.gradle` | It may add permissions or pods without explaining that a native rebuild is required |

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

## 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.

## Frequently asked questions

**Can Codex work with Expo and React Native CLI projects?** Yes. Codex works with both Expo and bare React Native workflows as long as AGENTS.md lists the correct start, build, and test commands. It can run Metro, read app.json, and edit TypeScript and native config files.

**Does Codex need a simulator or device to test React Native changes?** Codex cannot render the UI, so it cannot verify layout or touch behavior on its own. It can run typecheckers, linters, Jest, and export commands, but a human should still launch the app on a simulator or device for visual changes.

**How do I keep Codex from breaking the ios and android folders?** Keep native folders as generated, avoid editing them unless a task requires native code, and review any diffs in those folders carefully. After native changes, always rebuild the native app with npx expo run:ios or run:android.

**Can Codex write Jest tests for React Native components?** Yes. It can generate tests with @testing-library/react-native or React Native’s act, including mocks for fetch, navigation, and native modules. Review the assertions to make sure they test the intended behavior and handle async updates correctly.

---

**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/