Getting Started

Requirements

Requirement	Notes
Node.js >= 24	For the CDP bridge MCP server; every later major is supported
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
Session-bound Metro	Setup previews the project integration; literal pnpm ios or pnpm android starts or validates the allocated Metro

maestro-runner >= 1.1.24 is installed into rn-dev-agent’s versioned pin-cache as attested 1.1.24 by the host setup workflow. Claude’s SessionStart hook only verifies the pin-cache offline and prints the explicit pinned install command when remediation is needed. In Codex, invoke $rn-dev-agent:setup; after its read-only diagnosis, setup converges and verifies that attested runner before previewing project changes for consent. Replay never resolves from PATH, ~/.maestro-runner, or brew Maestro. Device control ships in-tree through the iOS/Android runners. Use the matching host setup workflow for guided remediation.

Installation

Jump to your host: Claude Code · Codex — or keeping up to date if it’s already installed.

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 --json

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, workflow helpers, health program, and 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 detail screen says No plugin hooks, that is expected. Codex exposes the cdp MCP server, eleven domain skills, and sixteen explicit workflow skills (27 total):

$rn-dev-agent:setup

Codex 0.145.0 is the live-refresh floor. Older hosts are restart-only. A same-app install/enable can update a subsequent turn; external CLI/manual changes require exiting and relaunching Codex. /mcp verbose inspects inventory only.

Codex setup first runs multi-axis read-only health, then manages a sentinel- bounded AGENTS.md block and other project wiring only after preview/consent. Claude setup continues to manage CLAUDE.md.

Keeping up to date

Enable auto-update in the host plugin manager. Manual update:

Claude: /plugin update rn-dev-agent@rn-dev-agent
        /reload-plugins
Codex:  codex plugin marketplace upgrade rn-dev-agent
        codex plugin add rn-dev-agent@rn-dev-agent --json
        # relaunch after this external mutation

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)

Run the matching setup workflow (/rn-dev-agent:setup in Claude or $rn-dev-agent:setup in Codex) to scaffold .rn-agent/dev-bridge.ts and .rn-agent/globals.d.ts. 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.

Both setup workflows preview this edit and ask before applying it.

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 manage the host-owned file

• Claude /rn-dev-agent:setup manages the rn-dev-agent block in CLAUDE.md.
• Codex $rn-dev-agent:setup manages only the sentinel-bounded rn-dev-agent block in AGENTS.md; it never changes Claude instruction files.

Both paths preview changes for confirmation and are idempotent: re-running setup skips an in-sync managed block and existing scaffold files.

Inspect the Claude template or the Codex AGENTS.md template before running setup.

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. The matching setup workflow 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 # or: codex

Claude’s SessionStart hook auto-detects the project and prepares supported dependencies. Codex has no plugin hooks. For either host, invoke its setup workflow when onboarding is incomplete:

Claude: /rn-dev-agent:setup
Codex:  $rn-dev-agent:setup

Claude walks its prerequisite checks and retries supported installations. Codex runs passive multi-axis health and recommends user-confirmed recovery without executing it. Both preview project wiring before writing. Once setup is ready:

Claude: /rn-dev-agent:rn-feature-dev add task priority levels with color coding and sort
Codex:  $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.

Want to watch it work? The observability web UI autostarts with the session. Invoke the matching observe workflow to get the URL and follow the live tool-call timeline, device mirror, and app-state panels in your browser.

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