--- name: rnx-setup description: Get Peach connected to your React Native app with no project setup --- # Peach setup you want to drive a React Native app with Peach from the CLI. this skill takes you from a running development server to a connected, pinned sim that every other Peach skill assumes exists. Peach requires no project setup or per-app install. if `rnx describe` already returns a tree, you're past this skill — load `/rnx-debug` for debugging or `/rnx-test` for writing tests. ## anti-patterns (read first) - **never `rnx claim --force` a sim held by another CLI.** the lease exists for a reason. forcing strands the other agent and corrupts the bridge state. use `rnx open --new` to start a fresh sim instead. - **don't switch sims mid-investigation.** pin once with `rnx use ` and keep it pinned. an unpinned command refuses to choose when more than one driveable sim is live. - **an empty `rnx list` is not "broken Peach".** it usually means the daemon is down, the dev server port is wrong, or the runtime is missing. walk the recovery checklist before reinstalling. - **keep one sim for your whole session.** the first `rnx open ` launches Chrome for Testing with an isolated profile. later opens reuse the saved sim and navigate it in place. use `rnx do reload` when the target has not changed: ```sh rnx open 8086 # first call creates your isolated sim rnx open 8090 # same sim, different app rnx do reload # same sim, same app rnx close # dispose it when you are done ``` `--new`, `--profile`, and `--ephemeral` create another isolated browser tree. use them only when separate storage or a genuinely concurrent sim is required. repeated new trees consume enough memory and CPU to starve other work on a shared machine. - **pin the sim before driving it.** `rnx open` records the new sim for the current CLI identity. read its id and pin it explicitly before a longer flow: ```sh rnx open 8086 rnx list rnx use rnx describe --sim ``` - **never retry-loop `rnx open` against a wedged or slow stack.** a connect timeout means diagnose the stack. do not retry. if the first launch never connects, each retry can create another browser tree before there is a saved sim to reuse. verify the development server and Peach runtime, then retry once after fixing the cause. ## first move ```sh rnx daemon status # the persistent service makes agent commands much faster rnx daemon install # enable it when missing on a supported personal machine rnx compat --json # scan the app's native package compatibility rnx open 8081 # load a metro/expo dev server rnx list # confirm exactly one sim is reachable rnx use # pin it for the rest of the workflow rnx describe # smoke test — should print a render tree ``` the background service keeps the local bridge and runtime ready between commands. without it, Peach still works by starting an on-demand bridge, but inspect, interaction, and test commands pay repeated startup cost. if the user declined it during onboarding, `rnx daemon install` is the direct way to enable it. CI does not need or install the service. bare `rnx` opens ConnectRN for a human to choose among local apps. agents and scripts should use `rnx open ` so the target is explicit. if you do not know the port, run `rnx open` with no target and pick from the detected dev servers. for hosted or unusual targets, pass the URL explicitly: ```sh rnx open 8081 # load a metro dev server rnx open https://my-app.local # load a hosted bundle ``` ## you're done when - `rnx list` shows your sim and no orphans - `rnx describe` returns a render tree, not an error - the same sim id appears in `rnx describe`, `rnx find`, and every subsequent command - `rnx get errors 5` and `rnx get requests 5` are quiet (or the warnings are ones you understand) - the compatibility scan's partial, unsupported, unknown, and version-mismatched packages have been summarized without treating its aggregate score as a pass/fail gate ## compatibility feedback requires approval run `rnx compat --json` from the app project root during setup. if the scan identifies a plausible missing Peach seam, or the running app gives concrete evidence that behavior is missing or broken specifically in Peach, summarize the package, expected behavior, actual behavior, and runtime evidence for the user. then offer to send that finding with `rnx report-issue`. **never submit a report automatically or behind the user's back.** wait for an explicit yes. only then run this from the app project root: ```sh rnx report-issue --yes "" ``` the command automatically attaches the local compatibility scan plus bounded CLI, runtime, operating-system, and architecture metadata. it does not attach source files, environment variables, terminal output, logs, screenshots, git data, or app data. `--dry-run` previews the attachment summary without sending. do not use `--yes` merely because the agent believes a report would be useful; it records the user's approval after the offer. ## recovery — common failure modes **`rnx list` is empty.** walk this checklist in order: ```sh rnx daemon status # is the bridge daemon up? rnx runtime list # is at least one engine runtime installed? rnx open # does loading explicitly work? ``` if the daemon is not installed: run `rnx daemon install`. if the registered daemon is down, run `rnx daemon restart`, or `rnx serve` in another shell for a foreground bridge. if no runtime is installed, `rnx open` installs it before launching. if open errors with "port unreachable": confirm your dev server is actually serving — the bundler has to be up before Peach can attach. **two sims appear unexpectedly.** an earlier `rnx claim` didn't release on exit. close the orphan explicitly: ```sh rnx list # note the stale id rnx close # release it cleanly ``` **`rnx open` errors with "no runtime".** the engine binary isn't installed. Run `rnx runtime install`, then retry `rnx open `. **`rnx open` times out ("timed out waiting for opened sim to connect").** do not retry in a loop. verify the development server first: `__soot/` must respond and the engine watchers must be running. inspect the driver diagnostic path printed by the failed command. restart the broken development stack at its supervisor, then retry once. Peach owns the isolated browser profile and its process tree; do not open the shell URL through an operating-system browser. **bridge disconnects mid-sim.** the WebSocket dropped (laptop slept, network blip). re-pin: `rnx use `. the daemon retries reconnection automatically; you usually just need to re-issue the command. **"sim held by another CLI".** another agent or your own previous CLI process has the lease. find it (`rnx list`), close it (`rnx close `), or start a clean sim (`rnx open --new`) — do **not** `rnx claim --force`. ## related - `/rnx-debug` — once setup is good, this is where you debug rendering, performance, and accessibility issues. - `/rnx-test` — write or run automated flows against the connected sim. - `/rnx-visual` — pixel-level rendering comparisons.