Gemini CLI React Native: a practical developer guide

Gemini CLI is a terminal coding agent that you start by running gemini in the root of a React Native project. It reads a GEMINI.md file for project-specific instructions and can plan changes, edit files, and run commands such as npm test or npx tsc --noEmit. For background on the agent itself, see Gemini CLI. This guide focuses on making it productive in Expo or bare React Native work.

Why Gemini CLI fits a React Native workflow

React Native development already lives in the terminal: Metro, Jest, TypeScript, npm, and platform build tools. Gemini CLI fits that workflow because it operates in the same project directory and can run the exact scripts you already use. It reads multiple files at once, so it can follow a component from a screen through navigation, props, and hooks to a test file. That makes it useful for repetitive refactors such as changing a prop across call sites, adding navigation routes, or keeping platform-specific .ios.tsx and .android.tsx files in sync. It also handles generated config files well when you give it rules, but it does not replace Xcode or Android Studio for visual layout or native debugging.

Give the agent a project brain with GEMINI.md

The single highest-leverage step is a good GEMINI.md in the project root. Gemini CLI reads this file at startup, so it should contain the commands that make your project testable and the rules that prevent common React Native mistakes. If you are new to the agent workflow, How to use Gemini CLI: a step-by-step guide gives a step-by-step walkthrough for starting and steering the agent. A concise example for a React Native project looks like this:

# React Native project rules for Gemini CLI

## Commands
- install: npm install
- test: npm test -- --watchAll=false
- typecheck: npx tsc --noEmit
- lint: npm run lint
- start Metro: npx expo start --clear
- export Android: npx expo export --platform android
- run iOS: npx expo run:ios

## Folder conventions
- src/screens: screen components
- src/components: reusable UI
- src/navigation: React Navigation stacks/tabs
- src/api: API client and hooks
- src/__tests__: Jest tests next to source

## Rules
- Do not edit ios/ or android/ manually unless the task requires native module code.
- For native dependencies, prefer Expo config plugins or ask before changing Podfile or build.gradle.
- Keep platform-specific code in src/**/*.ios.tsx and *.android.tsx.
- Never change babel.config.js, metro.config.js, or tsconfig.json without an explicit user request.
- Always run typecheck and tests after changing a shared component or hook.

Keep the file short enough that the agent actually follows it; if you add twenty rules, it will ignore the important ones.

The day-to-day loop: plan, small edits, verify

Treat Gemini CLI like a fast junior engineer who can type but should not own the final merge. Start from a clean git status, then ask for a plan before any file changes. Let the agent make one small logical change, run the project’s checks, and review the diff. If the change touches shared components or platform-specific files, run the checks yourself as well. This is the closed loop described in AI pair programming: how to work with a coding agent; it works especially well for React Native because broken changes often only appear at bundle time or inside a native module.

Typical prompts:

• Map the current React Navigation structure and suggest the smallest change to add a Settings screen without altering the existing bottom tabs.
• Add a useDebouncedValue hook in src/hooks/useDebouncedValue.ts, export it from the hooks index, and add a Jest test for the 300 ms default delay.
• Refactor ProductCard to take a variant prop instead of isFeatured; update the two call sites in HomeScreen and SearchScreen and run typecheck.
• Run npx tsc --noEmit and fix the first five type errors one at a time, showing the diff after each file.
• Review the current git diff and point out any React Native-specific risks before I commit.

Each prompt keeps the change bounded and verification explicit.

Where Gemini CLI is strong and where to watch closely

Gemini CLI handles text-heavy React Native tasks well: adding screens, refactoring components and hooks, updating API calls, writing tests, and fixing TypeScript errors. It is less reliable when a change requires native module knowledge, Metro resolution details, or platform build settings. In those areas, let the agent propose a change but verify it against the real toolchain before trusting it.

Watch closely around these React Native-specific areas:

• Native modules and linking: if the agent wants to edit Podfile, build.gradle, AndroidManifest.xml, or AppDelegate, require it to explain the exact native change and wait for approval.
• Metro and Babel: plugin order for react-native-reanimated or react-native-gesture-handler matters; an agent that reorders babel plugins can break the app at runtime.
• Expo config plugins: for Expo projects, prefer app.json plugin entries over manual native edits; otherwise expo prebuild will overwrite the change later.
• Platform-specific files: a change to Component.tsx without updating Component.ios.tsx and Component.android.tsx can cause silent drift.
• Package versions: the agent may add a package that requires a newer React Native or Expo SDK; check the peer dependencies before committing.

Testing React Native changes with the agent

Make the agent run non-interactive versions of your checks. For Jest, use npm test -- --watchAll=false so the command exits. For types, use npx tsc --noEmit. For a bundle-level sanity check, npx expo export --platform web or --platform android will catch import or Metro resolution errors before you open a simulator. For bare React Native, npx react-native bundle is an equivalent check. After a native-related change, run cd ios && pod install yourself and inspect the generated diff; do not let the agent assume the pods are fine. Always review git diff after each step and ask the agent to summarize which files changed and why.

For component tests, ask the agent to add tests with @testing-library/react-native, but warn it to mock native modules that use NativeModules unless you have a mock preset.

Parallel agents on one codebase with AgentVera

AgentVera runs Gemini CLI in a real terminal panel side by side with other coding agents. For React Native, the most valuable parts are parallel agents in separate git worktrees, so one can work on src/ while another touches ios/ without file collisions; an automatic second-model code review after each turn that links findings to file:line, which catches native module or Metro config mistakes early; checkpoints that let you undo a risky pod install or platform-specific edit in one click and replay the session; and token budgets that stop runaway processes but keep the conversation. For more on orchestrating multiple agents, see AI agent orchestration for coding: 5 patterns and tools.

Wrap-up: keep the agent on a short leash

The best results come from tight constraints: a clear GEMINI.md, one small change at a time, non-interactive verification commands, and a human review of every diff that touches native or platform-specific code. With that loop, Gemini CLI can take over a large share of the repetitive screen, hook, and test work in a React Native project, leaving the native integration decisions to you.