Skip to content

README.md

Latest commit

 

History

History
200 lines (145 loc) · 11.1 KB

README.md

File metadata and controls

200 lines (145 loc) · 11.1 KB

rn-dev-agent

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.

53 MCP tools | 5 agents | 13 commands | 249 tests | 46 best-practice rules | Full documentation

Install

/plugin marketplace add Lykhoyda/rn-dev-agent
/plugin install rn-dev-agent@Lykhoyda-rn-dev-agent
/reload-plugins

Setup

Navigate 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

Usage

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 Execute proof flow step by step, capture screenshots

Other commands

Command Purpose Docs
/rn-dev-agent:test-feature <desc> Test an already-implemented feature docs
/rn-dev-agent:debug-screen Diagnose and fix a broken screen docs
/rn-dev-agent:build-and-test <desc> Build app, then test docs
/rn-dev-agent:check-env Verify environment readiness docs
/rn-dev-agent:proof-capture <desc> Record proof video + screenshots docs
/rn-dev-agent:nav-graph Extract navigation graph docs

What makes this different

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.

App setup

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>

MCP Tools

53 tools across three layers. Full reference

Category Count Examples Docs
CDP (React internals) 26 cdp_component_tree, cdp_store_state, cdp_evaluate, cdp_set_shared_value, cdp_native_errors CDP tools
Device (native interaction) 14 device_find, device_press, device_fill, device_screenshot Device tools
Testing (E2E + proof) 13 proof_step, cross_platform_verify, maestro_run Testing tools

What's new in v0.23.0 (2026-04-16)

  • cdp_native_errors — surfaces simctl log/adb logcat entries for errors that fire before __RN_AGENT injects (missing native modules, bundle-fetch failures, FATAL EXCEPTIONs). cdp_status hints at it automatically when JS-layer signals are blank.
  • Multi-device correctness — cdp_connect accepts targetId/bundleId filters to disambiguate zombie Expo Go pages; inferPlatforms cross-checks simctl listapps and adb pm list; device_screenshot accepts platform and inherits from the connected CDP target.
  • Android speed parity — platform-aware CDP timeouts (2× on Android emulator) eliminate typeText false-negatives; real Android flow went from 16.1s/3 fails to 7.2s/0 fails in the same benchmark.
  • device_snapshot attachOnly: true — skip app launch when already running, saving the ~12s restart cascade.
  • 91 new unit tests (158 → 249) locking in the extracted cdp/* modules, platform filters, and native-error parsers.

Architecture

Claude Code
  ├── Skills (knowledge) + Agents (protocols) + Commands (entry points)
  │
  ├── MCP Server (CDP Bridge) ─── WebSocket → Metro → Hermes CDP
  │   52 tools: component tree, store state, profiling, network, interaction
  │
  └── Bash (device lifecycle)
      xcrun simctl / adb / maestro-runner / agent-device
          │                         │
     iOS Simulator           Android Emulator

Architecture details

Benchmarks

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

Troubleshooting

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.

Full troubleshooting guide

Security

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-check cdp_targets before 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.

Keeping up to date

Enable auto-update in the plugin manager (Marketplaces tab), or update manually:

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

Development

git 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-agent

Tests: cd scripts/cdp-bridge && npm test (148 tests, CI)

License

MIT