convez.ai
AgenteDesenvolvimento WebAvançado
Lykhoyda

RN Dev Agent

Lykhoyda/rn-dev-agent

Parceiro IA para dev React Native com verificação ao vivo no simulador

Ver no GitHub
InicialPluginScore · de 0 a 100

Agent Claude especializado em desenvolvimento React Native que explora codebases, projeta arquitetura, implementa features e verifica tudo ao vivo no simulador via Chrome DevTools Protocol. Inclui 74 ferramentas MCP, 5 agentes e 17 comandos com suporte a testes automatizados e captura de vídeos determinísticos.

Instalação

$npx convez-ai Lykhoyda/rn-dev-agent

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
21
Forks
1
Acompanhando
0
Saúde
42%
Último commit
há 1 dia
Versão
v2.2.2
Issues abertas
14
Contribuidores
3

Casos de uso

  • Implementar features completas em React Native com verificação automática
  • Explorar e documentar arquitetura de projetos RN existentes
  • Testar e debugar screens com evidência do Chrome DevTools Protocol
  • Gerar provas em vídeo de funcionalidades implementadas

Veredito

Agent robusto e production-ready para times React Native que precisam automação inteligente de dev com verificação real. Requer setup complexo (Node 22+, simuladores, CDP bridge) mas oferece pipeline completo: discovery → implementation → live verification → proof video. Ideal para acelerar ciclos de feature development em projetos estabelecidos.

README

A tradução para o português deste README ainda está na fila.

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.

74 MCP tools · 5 agents · 17 commands · 1180+ 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 10 prerequisites and fixes what it can automatically:

CheckRequiredAuto-install
Node.js >= 22 LTSYesNo
CDP bridge depsYesYes
rn-fast-runner (iOS)iOS targets only — ships in-tree; one-time xcodebuild build-for-testingNo
agent-deviceAndroid targets only — iOS no longer needs it (PR #164)Yes
maestro-runnerYesYes
iOS Simulator / Android EmulatorOne platformNo
Metro dev serverYesNo
CDP connectionYesAuto via cdp_status
ffmpegOptionalNo

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:

PhaseWhat happens
1. DiscoveryUnderstand the feature, create a task plan
2. ExplorationParallel agents map screens, store, navigation, conventions
3. QuestionsClarify edge cases, error states, data flow
4. ArchitectureDesign implementation with Opus-powered architect
5. ImplementationBuild the feature — store, components, navigation, testIDs
5.5. VerificationProve it works live — CDP health, component tree, store state, interaction, screenshot
6. ReviewParallel review agents check correctness and RN conventions
7. ProofRehearse off camera, persist a Maestro action with metadata, then record a deterministic replay — discovery never appears in the video

Other commands

Develop & test:

CommandPurpose
/rn-dev-agent:test-feature <desc>Test an already-implemented feature; auto-replays an existing Maestro action if one matches
/rn-dev-agent:debug-screenDiagnose 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
/rn-dev-agent:observeStart a read-only local web UI to watch the agent live — tool-call timeline, latest device screenshot, and route/store/component-tree panels. Prints a 127.0.0.1 URL to open in a browser.

Actions: replayable app flows + the LLM/pragmatic hybrid

An action is a saved Maestro flow the agent emits when /test-feature verification passes — not something you author. Each task is then composed of two regimes: pragmatic reusable actions for predictable parts (login, navigation, multi-step setup) and LLM-driven discovery for the part that's actually new. The agent uses actions as prologues to reach a known state before doing fresh interactive work. Measured: a 3-step wizard that took 13 min 55 s as an interactive walk runs in ~4 s when replayed — ~210× faster.

WhatA saved, parameterised flow with a metadata header and ${KEY} placeholders.
Where.rn-agent/actions/<name>.yaml. The plugin's home in your project is .rn-agent/.
Create oneRun /rn-dev-agent:test-feature <description>. The verified walk is saved as an action.
Run oneList 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.
Self-repairIf a testID changes, cdp_repair_action fuzzy-matches against the live snapshot, patches the YAML, and retries. Small UI drift absorbed; broken product logic surfaced, not auto-fixed.
Why hybridPure scripts don't adapt; pure LLM re-derives everything every session. Actions are the memory of the LLM loop — every successful verification adds one, every drift gets quietly absorbed, every truly broken flow escalates.

Full actions guide — why the hybrid matters, tool surface, comparison vs Detox/Maestro/pure-LLM

Setup & diagnostics:

CommandPurpose
/rn-dev-agent:setupInject CLAUDE.md tool-routing rules + nav-ref + Zustand exposure
/rn-dev-agent:doctor15-row diagnostic table — Node, CDP, rn-fast-runner (iOS), agent-device (Android), maestro-runner, simulators, Metro, helpers freshness, plugin version, CDP auto-reconnect mode
/rn-dev-agent:check-envQuick environment-readiness check
/rn-dev-agent:nav-graphExtract and inspect the app navigation graph
/rn-dev-agent:send-feedbackOpen a GitHub issue with sanitized environment context

Repo-local troubleshooting memory: the agent maintains a gitignored .rn-agent/local/troubleshooting.md per project (auto-captured failures + config notes), read at session start and updated at session end.

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

The plugin exposes 74 MCP tools across five families. See the tools reference for the full list.

FamilyWhat it's forExamples
CDPReact internals via Chrome DevTools Protocolcdp_status, cdp_component_tree, cdp_store_state, cdp_evaluate, cdp_native_errors, cdp_navigate, collect_logs
DeviceNative interaction with the simulator/emulatordevice_find, device_press, device_fill, device_screenshot, device_pick_date, device_batch
ActionsRecord / replay / self-repair persistent flows (guide)cdp_run_action, cdp_repair_action, cdp_record_test_save_as_action, cdp_record_test_*
TestingE2E replay and PR-ready proofproof_step, cross_platform_verify, maestro_run, maestro_test_all, cdp_auto_login
Macro-AssertsState-assertive replays — internal state, not pixelsexpect_redux, expect_route, expect_visible_by_testid, expect_text

What's new in v0.44.18 (2026-05-05)

  • Self-healing actions — new cdp_repair_action patches a stale testID via fuzzy match against the live snapshot when /run-action fails with SELECTOR_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_action orchestrates maestro_run + parser + cdp_repair_action + retry, then persists a RunRecord with structured autoRepair telemetry (passed / failed / refused / skipped, plus phase-level timing for MTTR analysis).
  • Auto-emission of recorded walks — new cdp_record_test_save_as_action turns a recorded walk into a first-class .rn-agent/actions/<id>.yaml with a full metadata header and initialised sidecar. Auto-promotes to status: active on first clean replay.
  • Macro-Asserts — expect_redux, expect_route, expect_visible_by_testid, expect_text for 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 — saveActionWithCAS detects 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).

Architecture

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
  │
  └── Device interaction
      ├── iOS    → in-tree rn-fast-runner (XCTest /command HTTP)  ← D1219, PR #164
      └── Android → agent-device CLI (daemon socket → fast-runner → CLI)
          │                         │
     iOS Simulator           Android Emulator

      Device lifecycle (boot / install / launch): xcrun simctl + adb
      E2E test execution: maestro-runner (preferred) / Maestro (fallback)

Architecture details

Benchmarks

38 stories completed on the test app (35 Ralph Loop + 3 Liquid Glass). Full benchmarks

ComplexityTimeCrashesManual interventions
Simple (search, toggle, store)3-5 min00
Medium (forms, charts, lists)5-10 min00
Complex (3-step wizard, onboarding)11-25 min00
Glass UI (BlurView, Reanimated, haptics)27-90 min01 (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

ProblemSolution
"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 errorAdd global.__ZUSTAND_STORES__ (setup)
Plugin not detected/plugin install rn-dev-agent@Lykhoyda-rn-dev-agent then /reload-plugins
Tools fail after upgradeRestart 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 reloadsNativeWind 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 screensagent-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.
Legacy AgentDeviceRunner re-appears on iOS simStale ~/.agent-device/daemon.json respawns the upstream runner alongside our in-tree rn-fast-runner. Since #202 the plugin terminates stale AgentDeviceRunner processes at session-open by default (scoped to the target simulator UDID) and clears orphaned ~/.agent-device/daemon.{json,lock}, so this self-heals. Opt out with RN_DEVICE_KILL_LEGACY=0; to clean up manually: pkill -f AgentDeviceRunner && rm -f ~/.agent-device/daemon.{json,lock}.
iOS device_* calls fail with "rn-fast-runner did not become ready"Build artifacts missing. Pre-build once: cd ${CLAUDE_PLUGIN_ROOT}/scripts/rn-fast-runner/RnFastRunner && xcodebuild build-for-testing -project RnFastRunner.xcodeproj -scheme RnFastRunner -destination "platform=iOS Simulator,id=<UDID>" -derivedDataPath ../build/DerivedData. After that, the runner spawns lazily on device_snapshot action=open.
iOS device_fill returns "main thread execution timed out" but text appears in the fieldKnown XCTest-internal quiescence behavior; the TS client treats this specific error as success on .type (meta.runnerTimeoutShim: true). The side-effect succeeded — proceed.

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.

The observability UI (/rn-dev-agent:observe) is opt-in and read-only: it binds to 127.0.0.1 on a random port, rejects cross-origin requests via Host-header + Sec-Fetch-Site checks, and serves no mutation endpoints. Tool arguments and payloads are deep-redacted (fail-closed — an unredactable value is dropped, not leaked) before they ever reach the stream, so tokens, passwords, and PII render as [REDACTED_*]. The recorder keeps only a small bounded in-memory ring buffer (recent events, never written to disk); nothing is exposed until you explicitly start the server.

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 (1180+ tests, CI)

License

MIT

Ver o original no GitHub

Bom para

Relacionados