A Claude Code plugin that turns Claude into a React Native development partner. It explores your codebase, designs architecture, implements features, then verifies everything live on the simulator — reading the component tree, store state, and navigation stack through Chrome DevTools Protocol.
70+ MCP tools · 5 agents · 16 commands · 1180+ tests · 46 best-practice rules · Full documentation
/plugin marketplace add Lykhoyda/rn-dev-agent
/plugin install rn-dev-agent@Lykhoyda-rn-dev-agent
/reload-pluginsNavigate to your React Native project and run the setup check:
cd /path/to/your-rn-app/rn-dev-agent:setup
This checks 9 prerequisites and fixes what it can automatically:
| Check | Required | Auto-install |
|---|---|---|
| Node.js >= 22 LTS | Yes | No |
| CDP bridge deps | Yes | Yes |
| agent-device | Yes | Yes |
| maestro-runner | Yes | Yes |
| iOS Simulator / Android Emulator | One platform | No |
| Metro dev server | Yes | No |
| CDP connection | Yes | Auto via cdp_status |
| ffmpeg | Optional | No |
If auto-install fails for any dependency, the setup command gives step-by-step manual instructions. Full setup guide
Tell Claude what to build:
/rn-dev-agent:rn-feature-dev add a shopping cart with badge, item list, and checkout flow
Claude runs an 8-phase pipeline — from understanding your codebase to verified code with proof screenshots:
| Phase | What happens |
|---|---|
| 1. Discovery | Understand the feature, create a task plan |
| 2. Exploration | Parallel agents map screens, store, navigation, conventions |
| 3. Questions | Clarify edge cases, error states, data flow |
| 4. Architecture | Design implementation with Opus-powered architect |
| 5. Implementation | Build the feature — store, components, navigation, testIDs |
| 5.5. Verification | Prove it works live — CDP health, component tree, store state, interaction, screenshot |
| 6. Review | Parallel review agents check correctness and RN conventions |
| 7. Proof | Rehearse off camera, persist a Maestro action with metadata, then record a deterministic replay — discovery never appears in the video |
Develop & test:
| Command | Purpose |
|---|---|
/rn-dev-agent:test-feature <desc> |
Test an already-implemented feature; auto-replays an existing Maestro action if one matches |
/rn-dev-agent:debug-screen |
Diagnose and fix a broken screen — gathers parallel evidence from CDP + native logs + component tree |
/rn-dev-agent:build-and-test <desc> |
Build app (local or EAS), install on device, then test |
/rn-dev-agent:proof-capture <desc> |
Rehearsal-gated video + screenshots + PR body |
Actions: replayable app flows
A saved, replayable flow through your app — login, navigate to settings, reach a known state. The plugin records actions automatically when verification passes; you replay them in seconds.
| What | A saved, replayable flow through your app (login, navigation, multi-step setup). |
| Where | .rn-agent/actions/<name>.yaml. The plugin's home in your project is .rn-agent/. |
| Create one | Run /rn-dev-agent:test-feature <description>. When verification passes, the plugin saves the verified walk as an action. |
| Run one | List with /rn-dev-agent:list-learned-actions; replay with /rn-dev-agent:run-action <name>. The agent also picks an action automatically when it needs to reach a known state (e.g. logged-in home) before doing new work. |
| Self-repair | If a testID changes, the plugin patches the action against the live UI and retries. Small UI drift is absorbed without re-recording; broken product logic is not auto-fixed. |
| Why | Known flows replay in seconds instead of being rediscovered interactively. Repeated setup work like login becomes one fast step. |
Setup & diagnostics:
| Command | Purpose |
|---|---|
/rn-dev-agent:setup |
Inject CLAUDE.md tool-routing rules + nav-ref + Zustand exposure |
/rn-dev-agent:doctor |
12-row diagnostic table — Node, CDP, agent-device, maestro-runner, simulators, Metro, helpers freshness, plugin version |
/rn-dev-agent:check-env |
Quick environment-readiness check |
/rn-dev-agent:nav-graph |
Extract and inspect the app navigation graph |
/rn-dev-agent:send-feedback |
Open a GitHub issue with sanitized environment context |
Experience Engine (cross-session learning): /rn-dev-agent:rn-agent-export, /rn-dev-agent:rn-agent-import, /rn-dev-agent:rn-agent-health, /rn-dev-agent:rn-agent-compact — see docs.
Live verification — After implementing a feature, Claude connects to your running app via CDP, navigates to the screen, checks the component tree, exercises interactions, and confirms store state. No "trust me it works."
46 best-practice rules — Integrated from Vercel's React Native skills, covering crash prevention, list performance, animations, and state management. Applied during architecture and review. Browse rules
5 specialized agents — tester, debugger, code explorer, architect, reviewer. Each runs a focused protocol for its domain.
Most apps need zero setup — the plugin reads the React fiber tree directly via Metro's CDP endpoint.
Zustand stores — one line in your app entry (details):
if (__DEV__) {
global.__ZUSTAND_STORES__ = { auth: useAuthStore, cart: useCartStore };
}Redux — auto-detected, no setup needed.
testIDs — add to interactive elements for reliable queries:
<Pressable testID="checkout-button" onPress={handleCheckout}>
<Text testID="cart-badge">{itemCount}</Text>
</Pressable>The plugin exposes a wide surface area of MCP tools across four families. See the tools reference for the full list.
| Family | What it's for | Examples |
|---|---|---|
| CDP | React internals via Chrome DevTools Protocol | cdp_component_tree, cdp_store_state, cdp_evaluate, cdp_native_errors, cdp_record_test_*, cdp_repair_action |
| Device | Native interaction with the simulator/emulator | device_find, device_press, device_fill, device_screenshot, device_pick_date |
| Testing | E2E replay and PR-ready proof | proof_step, cross_platform_verify, maestro_run, cdp_run_action |
| Macro-Asserts | State-assertive replays — internal state, not pixels | expect_redux, expect_route, expect_visible_by_testid, expect_text |
- Self-healing actions — new
cdp_repair_actionpatches a staletestIDvia fuzzy match against the live snapshot when/run-actionfails withSELECTOR_NOT_FOUND. Guardrails: refuses on human edits (mtime check), refuses past 3 repairs in 24h, refuses on snapshot infrastructure failure. - Auto-repair-aware action replay — new
cdp_run_actionorchestratesmaestro_run+ parser +cdp_repair_action+ retry, then persists aRunRecordwith structuredautoRepairtelemetry (passed / failed / refused / skipped, plus phase-level timing for MTTR analysis). - Auto-emission of recorded walks — new
cdp_record_test_save_as_actionturns a recorded walk into a first-class.rn-agent/actions/<id>.yamlwith a full metadata header and initialised sidecar. Auto-promotes tostatus: activeon first clean replay. - Macro-Asserts —
expect_redux,expect_route,expect_visible_by_testid,expect_textfor state-assertive replays. Maestro asserts pixels; these assert internal state. Differentiated capability over Maestro Cloud / KaneAI / BrowserStack. - testID-keyed
device_batch— re-resolves via fresh fiber-tree snapshot per call, immune to stale-ref-across-step-transitions failures. - Three-layer architecture — Workflow (rn-feature-dev) / Discovery (CDP + device tools) / Reproducible Actions is the canonical mental model. See architecture.
- Atomic YAML+sidecar pair-write — sidecar-first ordering with future-mtime buffer guarantees no false-positive "external edit" alarms even on partial-write failures (D1101 / issue #101).
- CAS read-modify-write protection —
saveActionWithCASdetects concurrent writer races on the same actionId and retries, so RunRecord history doesn't lose entries under heavy parallel runs (issue #117). - 1180+ unit tests in cdp-bridge (was 994 in v0.44.5, 249 in v0.23.0).
Claude Code
├── Skills (knowledge) + Agents (protocols) + Commands (entry points)
│
├── MCP Server (CDP Bridge) ─── WebSocket → Metro → Hermes CDP
│ 74 tools: component tree, store state, profiling, network, interaction, recording, self-healing
│
└── Bash (device lifecycle)
xcrun simctl / adb / maestro-runner / agent-device
│ │
iOS Simulator Android Emulator
38 stories completed on the test app (35 Ralph Loop + 3 Liquid Glass). Full benchmarks
| Complexity | Time | Crashes | Manual interventions |
|---|---|---|---|
| Simple (search, toggle, store) | 3-5 min | 0 | 0 |
| Medium (forms, charts, lists) | 5-10 min | 0 | 0 |
| Complex (3-step wizard, onboarding) | 11-25 min | 0 | 0 |
| Glass UI (BlurView, Reanimated, haptics) | 27-90 min | 0 | 1 (Metro restart) |
Libraries tested: react-hook-form, zod, @tanstack/react-query, @gorhom/bottom-sheet, @shopify/flash-list, zustand, react-native-svg, expo-notifications, react-native-reanimated, react-native-gesture-handler, expo-haptics, expo-blur
| Problem | Solution |
|---|---|
| "Metro not found" | Start Metro: npx expo start or npx react-native start |
| "No Hermes target" | Open the app on simulator, ensure Hermes is enabled |
| CDP rejected (1006) | Close React Native DevTools, Flipper, or Chrome DevTools |
| Zustand store error | Add global.__ZUSTAND_STORES__ (setup) |
| Plugin not detected | /plugin install rn-dev-agent@Lykhoyda-rn-dev-agent then /reload-plugins |
| Tools fail after upgrade | Restart Claude Code (why) |
| Spawned subagent says "MCP tools unavailable" | Never spawn rn-tester / rn-debugger via Task tool — MCP stdio doesn't propagate to subprocesses (GH #31). Use /rn-dev-agent:test-feature or /rn-dev-agent:debug-screen instead; protocols run inline in the parent session. |
| Blank white screen after many reloads | NativeWind stylesheet corruption after 5+ cdp_reload cycles. Kill Metro, restart it, relaunch the app. cdp_status warns when reload count is high. |
device_scroll times out on Reanimated screens |
agent-device daemon waitForIdle deadlocks with Reanimated worklets. Fixed in v0.22.0 — scroll routes through fast-runner HID synthesis. Ensure fast-runner is healthy via device session. |
The cdp_evaluate tool runs arbitrary JavaScript in your app's Hermes runtime with full access to component tree, store state, AsyncStorage, and any in-memory secrets. This is intentional — runtime introspection is what makes the plugin useful for debugging — but it means only run this plugin against apps where you trust the agent's prompts.
Recommended usage:
- Local dev environments only. Do not point the plugin at production builds, store-signed apps, or any app holding real user data.
- Treat the agent like a developer with shell access to your laptop. Any prompt that reaches
cdp_evaluate(directly or through another tool that calls it) can read or mutate your app's runtime state. - Don't connect to CDP targets you didn't intentionally launch. The plugin filters Metro endpoints to
127.0.0.1/localhost, but if you're running multiple Hermes targets on your machine, double-checkcdp_targetsbefore relying on tool output.
The plugin makes no attempt to sandbox cdp_evaluate calls. If you need that, gate the agent's tool access through Claude Code's permission prompts rather than trusting the tool layer to enforce safety.
Enable auto-update in the plugin manager (Marketplaces tab), or update manually:
/plugin update rn-dev-agent@Lykhoyda-rn-dev-agent
/reload-pluginsgit clone https://github.com/Lykhoyda/rn-dev-agent.git
cd rn-dev-agent/scripts/cdp-bridge && npm install && npm run build && cd ../..
cd /path/to/your-rn-app && claude --plugin-dir /path/to/rn-dev-agentTests: cd scripts/cdp-bridge && npm test (1180+ tests, CI)
MIT