Getting Started

Requirements

Requirement	Notes
Node.js >= 22.18 (LTS)	For the CDP bridge MCP server
Claude Code CLI or Codex CLI	Use the host agent you want to run rn-dev-agent from
iOS Simulator or Android Emulator	At least one platform
Metro dev server running	npx expo start or npx react-native start

maestro-runner is auto-installed on first plugin load. Device control ships in-tree — the rn-fast-runner (iOS) and rn-android-runner (Android) runners build/install on first use; no external CLI is required. If anything is missing, run /rn-dev-agent:setup for guided diagnostics with manual fallback instructions.

Installation

Claude Code

From inside Claude Code:

1. Add the marketplace:

   /plugin marketplace add Lykhoyda/rn-dev-agent

2. Install the plugin:

   /plugin install rn-dev-agent@rn-dev-agent

3. Reload plugins to activate:

   /reload-plugins

For local source development, point Claude Code at the repository root:

claude --plugin-dir /path/to/rn-dev-agent

The root .claude-plugin/marketplace.json resolves the actual Claude package from packages/claude-plugin/. Use /path/to/rn-dev-agent/packages/claude-plugin only when a tool asks for the plugin package root directly.

Codex

Install from the marketplace (recommended):

codex plugin marketplace add Lykhoyda/rn-dev-agent
codex plugin add rn-dev-agent@rn-dev-agent

The repo’s .agents/plugins/marketplace.json resolves the Codex payload from packages/codex-plugin/, and the installed plugin is fully self-contained (bundled MCP runtime, native runner sources, runner manifest).

For a local checkout instead, Codex uses a separate package directory:

/path/to/rn-dev-agent/packages/codex-plugin

When installing locally through Codex, select or register packages/codex-plugin, not the repository root and not packages/claude-plugin. That directory owns .codex-plugin/plugin.json, .mcp.json, the package-local skills, and the bundled MCP runtime at rn-dev-agent-core/dist/supervisor.js.

Codex does not load Claude Code hooks. If the Codex plugin detail screen says No plugin hooks, that is expected; the active Codex surfaces are skills plus the cdp MCP server.

After installing, navigate to your React Native project and run the setup check:

/rn-dev-agent:setup

This verifies all 9 prerequisites, retries failed installations, and gives manual instructions for anything it can’t fix automatically.

Keeping up to date

Enable auto-update in the plugin manager (Marketplaces tab). With auto-update enabled, Claude Code checks for new versions at startup.

Manual update:

/plugin update rn-dev-agent@rn-dev-agent
/reload-plugins

What happens after install

The verification loop

1. Implementwrites the feature
2. ConnectCDP over WebSocket
3. Navigateto the changed screen
4. Readcomponent tree + store state
5. Exercisetaps the real UI
6. Reportwith evidence

report with evidence — not "it should work now"

Phase 6 of /rn-feature-dev: the agent proves the feature on the simulator before reporting done.

Setup for your app

No setup needed for most apps

The plugin connects to your running app via Metro’s CDP endpoint and reads the React fiber tree directly.

Zustand stores (one bridge call)

/rn-dev-agent:setup scaffolds .rn-agent/dev-bridge.ts and .rn-agent/globals.d.ts into your project. Then add a single registration call alongside your store definitions:

// App.tsx or app/_layout.tsx
import { getBridge } from './.rn-agent/dev-bridge';

getBridge()?.registerStores({
  auth: useAuthStore,
  cart: useCartStore,
});

No __DEV__ guard at the call site — getBridge() returns null in production and the optional chain is a no-op. Zero production cost. The bridge handles the dev-only global assignment internally.

/rn-dev-agent:setup proposes this edit automatically; you don’t have to write it by hand.

Redux

Auto-detected. No setup needed.

testIDs

Add testID to interactive elements for reliable component queries:

<Pressable testID="checkout-button" onPress={handleCheckout}>
  <Text testID="cart-badge">{itemCount}</Text>
</Pressable>

Project instructions: let /setup do it

/rn-dev-agent:setup injects the plugin’s tool-routing rules into your project’s CLAUDE.md automatically. It also scaffolds the bridge files and the .rn-agent/ directory in one pass.

The injection is idempotent — re-running /setup skips already-applied blocks.

If you want to inspect the rules first, see the CLAUDE.md template — the body after the --- separator is what gets appended to your project’s CLAUDE.md.

Your agent’s saved flows live in .rn-agent/

The plugin’s home in your project is .rn-agent/. Saved actions, the UI skeleton, navigation graph, and runtime state all live there. /setup scaffolds the directory; /doctor reports on its health.

See the Actions guide for what an action is, how to record one, and how the agent uses them.

First run

Navigate to your React Native project and start building:

cd /path/to/your-rn-app
claude

On startup the plugin auto-detects your project and installs dependencies. If anything fails, run:

/rn-dev-agent:setup

This checks all 9 prerequisites, retries failed installations, and gives manual instructions for anything it can’t fix automatically. Once everything is green:

/rn-dev-agent:rn-feature-dev add task priority levels with color coding and sort

The plugin handles the rest — 8 phases from understanding to verified code with proof screenshots.

Install from source (development)

git clone https://github.com/Lykhoyda/rn-dev-agent.git
cd rn-dev-agent
corepack enable
corepack yarn install --immutable
corepack yarn workspace rn-dev-agent-core build
corepack yarn build:host-runtimes

Claude Code local path:

cd /path/to/your-rn-app
claude --plugin-dir /path/to/rn-dev-agent

Codex local plugin package path:

/path/to/rn-dev-agent/packages/codex-plugin