Historical version and verification scope
This is the complete main guide at pinned historical commit c522fac1b5779f5f5792fbbe71aac48b145b3c9d. It belongs to the old rn-iso version dated2026-08-26 at19:58:51 UTC;the catalog name and original metadata are retained. Checked on2026-10-18 UTC against the exact file,Git blob and full text. Chinese is a complete translation;code examples and original metadata are retained. Installation,authentication,device,cleanup and publishing commands are historical documentation and were not executed here. Current installation and runtime outcomes were not tested. Catalog repository,name,identity,URL,install command and install count are preserved.
Complete main guide
rn-iso -- the RN / Expo CLI for agents
You are an AI agent working on a React Native / Expo project, possibly alongside other agents working on different projects or worktrees. The RN and Expo CLIs are built for a human at a terminal: interactive pickers, progress bars, ephemeral colored output, thousands of lines you pay for in tokens whether the build succeeded or not. rn-iso reimplements the handful of operations an agent actually needs, with a deliberately small option surface: never prompt, print little, capture everything, expose state as JSON.
Invoke the CLI via npx: npx rn-iso <command>. Don't npm install -g.
npx usually resolves the latest published version, but not always: a stale entry in the npm cache (or a different node version's cache) can serve an old one, and an old CLI silently lacks commands this file documents. Check once per session -- npx rn-iso --version -- and use npx rn-iso@latest if it disagrees with the version stamped at the bottom of this file.
In a repo whose .npmrc pins a private registry (registry=https://<host>/..., common in company monorepos), npx tries to fetch rn-iso from THAT registry and fails -- typically npm error code E401 (expired token) -- because rn-iso is published on the public npm registry. Point npx at the public registry for this one package: npx --registry=https://registry.npmjs.org rn-iso <command> (and the same on rn-iso@latest). An E401/E404 on npx rn-iso is almost always this, not a broken install.
Read the CLI's own docs for anything specific
This file covers the rules that do not change between releases. For exact flags, the JSON payloads, and error remedies, ask the binary you are actually running:
npx rn-iso guide # topics
npx rn-iso guide lifecycle # the full flow, end to end, and the whole option surface
npx rn-iso guide facts # the --json payloads, field by field
npx rn-iso guide metro # the dev server, the supervisor, and starting your own
npx rn-iso guide logs # querying the log timeline; what --errors means
npx rn-iso guide errors # every error code and what to do about it
npx rn-iso guide cleanup # what reclaims devices, and disk hygiene
npx rn-iso guide settings # which settings are honoured, and where they live
That output is generated by the installed CLI, so it cannot be out of date the way this file can. If this file and guide disagree, guide is right -- this copy may be older than the CLI. (Refresh it with npx skills.)
The model, in five rules
-
Every device rn-iso uses is one rn-iso created, named
rn-iso-<label>, and recorded as owned. It never boots, adopts, or destroys a device it did not create. Teardown of the owner destroys the device, not just its assignment. There is no exception: physical-device support was removed, so there is no path that touches hardware. -
Identity is proven before anything is destroyed. A port is not identity and a recorded id is not identity. Before killing a dev server or a device, rn-iso re-checks against live state and refuses when it cannot prove ownership. A refusal means something is genuinely unexpected -- investigate it, don't reach for
--force. -
You are not the only agent on this machine. Never assume
bootedis your simulator; never call a device verb without an explicit udid/serial; never hardcode a port. Read them from the--jsonpayload every time. -
Capture is unconditional and stdout is small. Every bundler event, in-app
console.log, redbox, device log line and build transcript is written to<root>/.rn-iso/logsas NDJSON. Commands print on the order of ten lines; a failing build prints the extracted compiler diagnostic and a log path, never the transcript. There is no flag to make anything noisier, because nothing was ever ephemeral. -
Blocking is opt-in, and errors are codes. Long-running things return immediately unless you pass
--follow/--wait. Every refusal carries{code, message, remedy}-- branch oncode, never on the message text.
The flow
cd "$(npx rn-iso worktree create app-412 --carry-ignored)" # 1. isolated worktree (--base takes any ref)
npx rn-iso start # 2. dev server; blocks until healthy
npx rn-iso ios # 3. build/install/launch on YOUR device
npx rn-iso logs --errors --json # 4. the crash, symbolicated
# ... edit the JS; Fast Refresh applies it, no rn-iso command involved ...
npx rn-iso logs --since 30s --level error # 5. empty output, exit 0 = it works
npx rn-iso stop # 6. pause: reclaim ~1.5 GB
npx rn-iso worktree remove # 7. done with the branch; dies whole
Step 2 before step 3, always. ios / android never start the bundler. If nothing that verifies as this workspace's dev server holds the reserved port, they refuse in about a second with RN_ISO_NO_METRO rather than spending four minutes producing an app that cannot load a bundle. --no-metro-check overrides it when you know what you are doing.
start reserves the port, hosts the dev server under a detached per-workspace supervisor, and does not return until the server verifies as this project's -- so there is no backgrounding idiom, no sleep, and no poll loop. It is idempotent: run it twice and you get one supervisor, exit 0. A dev server you started is detected, left alone, and reported with supervisorPid: null.
ios / android boot the owned device, check the port, fingerprint the native inputs, and install a build another workspace already made when the fingerprint matches -- so the second workspace on a commit costs a boot, not four minutes of xcodebuild. Then they install, launch the app wired to the reserved port, and attach a device-log collector. Repeat only when a NATIVE input changes; a JS edit needs nothing. While pod install or the compiler actually runs, a heartbeat lands on stderr about every 30s -- elapsed time plus the phase's current line -- so a multi-minute build is never indistinguishable from a wedged one; silence well past a minute means something is genuinely stuck.
rn-iso logs --errors is the query the whole design exists to make possible: the redbox with a symbolicated stack, the Metro resolution failure, the native crash, from one merged timeline. Do not read the NDJSON files directly -- npx rn-iso guide logs documents the filters and the record shape.
On APFS, worktree create --carry-ignored clones every gitignored path (node_modules, ios/Pods, build codegen) instead of leaving you to reinstall, always skipping .rn-iso/ at any depth (this workspace's own derived data, logs and supervisor pidfile -- never right to carry, so it is code rather than configuration) plus anything a repo-root .worktreeexclude adds. The clone matches the source worktree, not this branch's manifests, so reinstall if the branch changes them. Off by default: outside APFS the clone falls back to a real copy of every byte, which worktree create warns about.
Read what --carry-ignored prints; it is not just a count. Two warnings there are the difference between building and losing half an hour:
- No node_modules among them -- the source worktree has none, so the clone carried nothing you can build against. Install before doing anything else.
- Carried Pods do not match Podfile.lock --
ios/Podsis gitignored and cloned,ios/Podfile.lockis tracked and comes from the branch, so the two can disagree.rn-iso iosdetects this and runspod installitself; the warning matters if you build by hand, because xcodebuild reportsThe sandbox is not in sync with the Podfile.lockonly after every pod has compiled.
One more consequence of "the clone matches the source, not the branch": a carried path that the BASE's .gitignore does not ignore (an ios/ dir carried into a branch that gitignores it differently, a generated file the branch stopped ignoring) shows up as untracked churn in git status -- and worktree remove will later, correctly, refuse over it. Restore it first (git checkout -- . for modified tracked files, git clean -fd <path> for untracked ones -- the refusal names the right command per class) rather than reaching for --force.
A foreign process on your reserved port is reported, not silently tolerated. rn-iso status warns about it (port 8082: pid 900 runs from /elsewhere), ios / android refuse with RN_ISO_NO_METRO, and stop refuses to kill it without --force. start re-reserves a fresh port instead, so the project is never stranded. npx rn-iso guide errors lists the causes -- most often a bundler started from a monorepo's root instead of the app directory.
Destructive commands -- ask the user first
Destruction lives in exactly two commands. Everything else, including stop, is safe.
worktree remove --forcediscards uncommitted changes and untracked files permanently. Plainworktree removedeletes the worktree and reaps its owned device; it refuses when the tree is dirty.pod installchurn no longer causes that refusal: when the only dirt left is<app>/ios/Podfile.lockor<app>/ios/*.xcodeproj/project.pbxproj, tracked and unstaged, rn-iso restores those files itself and proceeds, printingrestored <path> (pod install churn; the worktree is being removed)for each. They are inside a directory about to be deleted wholesale, and a lockfile change anyone intended would have been committed. One other dirty path and the whole set is refused, churn included -- that fail-closed rule is what keeps this from ever eating real work. When it does refuse over something else, restore what it names and retry rather than forcing. The refusal names the right command per class:git checkout --for modified tracked files,git clean -fd(or anrm) for untracked ones, which checkout cannot clear. The workspace's own.rn-iso/never counts as dirt -- it dies with the worktree by design -- and neither does a.gitignorethat is nothing but the.rn-iso/entrystart/ios/androidadd themselves: whether the block was appended to a tracked file (restored) or the whole file was created in a repo that had none (deleted), checked line by line, and one other line either way and it refuses again. So rn-iso's own writes can never be the reason for a refusal. It takes no argument: run it from anywhere inside the worktree, including a monorepo app dir, and it resolves the enclosing worktree root.npx rn-iso guide errorsshows how.gc --deletedrops dead project entries and deletes the orphanedrn-iso-*devices it reported, potentially tens of GB of simulator. With--older-than <days>it also reaps the device of a project nothing has touched that long. With--allit empties the shared build caches, which every project on the machine then pays to refill. A baregconly reports -- it writes nothing and is always safe.stop --forceis the one flag on a non-destructive command: it kills a process on the reserved port that rn-iso could not identify as yours. It deletes nothing. Plainstophalts the supervisor, reaps the device-log collectors, shuts the owned device down (never deletes it) and frees the port, so coming back to the branch costs a boot rather than a create and a reinstall. There is no--deleteon it, deliberately -- an agent reaching forstopto reclaim memory must not have one within reach of a typo.
Capacity
A booted iOS sim is roughly 1-2 GB of RAM, an Android emulator 2-3 GB. On a 16 GB machine plan for 2-3 live environments, not more. By default nothing enforces this. npx rn-iso status reports every workspace on the machine (it is machine-wide by default, not scoped to where you are standing), which is how you find out you would be the fourth. One caveat when counting: a monorepo workspace holds TWO registry entries -- the worktree root (which only reserves the label) and the app directory -- so the root's entry carries labelOnly: true in --json and is relabelled in the human view; count only the entries without it. Tear down what you're done with before creating more.
Opt-in concurrency limits (unlimited by default). When a machine cannot host as many parallel builds or devices as there are agents, two machine-level caps can rein it in -- set them under a top-level concurrency key in ~/.rn-iso/config.json ({ "concurrency": { "maxBuilds": 2, "maxDevices": 3 } }), or via RN_ISO_MAX_BUILDS / RN_ISO_MAX_DEVICES which override the file. maxBuilds caps how many builds compile at once (a full slate WAITS -- it is a semaphore taken after the single-flight lock, so a waiter installing another workspace's artifact never burns a slot); maxDevices caps how many rn-iso-owned devices are booted at once, and a new ios/android at that cap is refused with RN_ISO_AT_CAPACITY (interactive-shaped: it does not queue -- stop an environment or raise the cap). Unset, 0, or any non-positive value means no enforcement. There is no rn-iso config command; these are files and env vars. See npx rn-iso guide lifecycle and guide settings.
Skipping the build when nothing native changed
Most changes touch no native input, and those should not compile anything. rn-iso ios / rn-iso android fingerprint the native inputs with @expo/fingerprint before building, and install a cached .app/.apk from ~/.rn-iso/build-cache when that fingerprint already has one -- the fingerprint <hash> hit line. The fingerprint is scoped to the platform being built (platforms: ['ios'] / ['android']), so a change under ios/ cannot move the Android cache key and vice versa. That matters more than it sounds: a hermes-engine podspec that bakes an absolute path into ios/Podfile.lock makes the iOS tree differ between worktrees by construction, and an unscoped hash turned that into a 100% Android cache miss across worktrees. The two platforms therefore print different hashes for the same commit -- that is correct, not a bug. Without @expo/fingerprint resolvable from the project they refuse with RN_ISO_NO_FINGERPRINT rather than compiling from scratch forever.
There are two levels. Level one is that local cache, shared by every worktree on the machine. Level two -- Expo projects only -- is the build-cache provider the project already configured for Expo (expo.buildCacheProvider: "eas", or a module of its own): it is consulted only when level one misses, a hit is copied into level one on the way past (cache remote hit (eas) -> stored locally), and a fresh build is stored locally and handed back to the provider. Every provider call is time-bounded and every failure is a note, so a slow, unauthenticated or misconfigured remote cache costs a build, never the run. The "eas" provider gets one extra, cheap check first, because it is the one that cannot report its own failures (it catches every eas-cli error and returns null, so a dead session looks exactly like an empty cache): a bounded eas whoami, once per run. Definitively logged out -> one yellow line (cache eas is not authenticated -- run \eas login` (or set EXPO_TOKEN); building with the local cache only) and the remote tier is skipped for that run; authenticated as somebody who does not cover the project's expo.owner-> a line naming both, and the cache is still consulted. Offline or unknown changes nothing at all.doctor` reports the same three states standing still. rn-iso never configures a provider and never suggests changing one; a bare React Native project has no provider concept and stays purely local, with no network call at all.
--no-build-cache on either command looks nothing up -- neither level -- and builds fresh. It still stores the result (replacing the entry it was told not to trust) and still uploads it, and the --json payload says cacheSkipped: true so you can tell that run from an ordinary miss. Reach for it when a cached artifact is suspect, not as a habit: a needless full build costs every parallel agent the machine's cores.
cacheHit in the payload is a LEVEL, not a boolean: "local", "remote", or false.
Two agents on the same commit no longer both compile it. The cache only helps the second workspace once the first has finished, so agents that start within the same minute all miss it. When both levels miss, ios / android take a lock on the fingerprint: exactly one workspace compiles, and the others wait for its artifact and install that (build waited 12m41s for /w/app-412's build -> installed from cache), reporting cacheHit: "local" plus waitedForBuild: {pid, ms}. Waiting is not a hang, and it cannot deadlock -- the lock is held by a pid, so a builder that crashes, is killed, or whose build fails frees it and one of the waiters takes over and builds. A progress line naming the builder and its log appears every 30s. Don't reach for --no-build-cache to escape a wait: it never waits and never takes the lock, which is exactly how you get the duplicate 19-minute compile back. npx rn-iso gc lists any build in progress, and clears the locks whose builder is gone.
Setting a repo up for this is the rn-iso-init skill's job, not a command's. There is no rn-iso init -- it was removed, along with the scripts/dev it generated. Every edit that setup needs lands in a file the project already owns (a metro.config.js with its own transformer, a Podfile with existing post_install logic, an app config that may be TypeScript), so it is judgement rather than generation: npx rn-iso doctor reports the findings, read-only, and the rn-iso-init skill is the playbook for applying each one by hand in the repo's own style. The one thing that never needed judgement -- .rn-iso/ in .gitignore -- is now self-ensured: start, ios and android each add the entry if it is missing and say so once on stderr (note added .rn-iso/ to .gitignore). Commit that .gitignore change with your PR. It is a one-line repo-hygiene edit every checkout of this repo wants, and committing it is what stops it being rewritten: until it is in the repo, every fresh worktree writes it again, and a tree that has run rn-iso fingerprints differently from one that never has -- so the first build in a new worktree can miss a cache entry it should have hit. If a repo has its own run script wrapping rn-iso, read it first: it may add steps this repo needs, and it wins over anything you would invent. (Earlier versions generated a WORKFLOW.md and a scripts/dev; a repo that still has either owns it now, and neither describes this version.)
These caches never evict themselves. Every npx rn-iso gc run reports what they have grown to -- each one tagged registered or detected -- and gc --delete --older-than <days> trims the entries nothing has used. Trim rather than empty: gc --delete --all empties them whole -- the only way to clear an index-backed cache like Xcode's CAS -- and costs the next build in every project the time the cache was saving.
Command surface
Ten commands: doctor (what is silently costing build time) · worktree create|remove · start (dev server under a supervisor, blocks until healthy) · stop (the inverse of start) · ios · android (build/install/launch, from cache when nothing native changed) · logs (query the captured NDJSON timeline) · status (devices, ports, supervisor health, last build, error counts) · gc (dead entries, orphaned devices, records of devices that no longer exist, and the shared build caches) · guide
That is all of it. There is no init -- repo setup is the rn-iso-init skill applying doctor's findings by hand, and the one safe generated edit (.rn-iso/ in .gitignore) is self-ensured by start/ios/android. There is also no up, no release, no shutdown, no config, no build-cache, no worktree list -- status covers the last one, ios/android absorbed the build cache, settings are files (guide settings), and destruction consolidated into worktree remove and gc --delete. Run npx rn-iso <command> --help for flags, or npx rn-iso guide for the reference.
When things go wrong
- A build failed. Read the extracted diagnostic rn-iso printed, not the log. The full transcript is in
.rn-iso/logs/build-<platform>.ndjsonif you genuinely need it -- it holds this run only (each build starts the file over), and it is almost never worth the tokens. The failure carries a code (RN_ISO_BUILD_FAILED,RN_ISO_DEPS_FAILED, ...) --npx rn-iso guide errorsmaps every one to a remedy. iosrefused withRN_ISO_NO_METRO. Runnpx rn-iso startfirst. That is the whole fix, and the refusal cost you a second instead of four minutes.starttimed out. It prints its evidence before it exits -- read it: the last lines of.rn-iso/logs/supervisor.log(the supervisor's raw stdio) when that file has any, plus this attempt's error records from the log timeline, which is where an Expo child's death cry (a config PluginError, a bad app config) actually lands.npx rn-iso logs --errorsreplays the full records. A cold Metro on a big graph may genuinely need longer:npx rn-iso start --wait 180. Under--jsona failure still puts one parseable line on stdout, the same{code, message, remedy}contractios/androiduse:RN_ISO_METRO_TIMEOUTmeans the supervisor is alive but nothing is serving yet,RN_ISO_SUPERVISOR_EXITEDmeans the dev server failed outright and nothing is left to stop.launched: "unverified"in the--jsonpayload is not success. The app started but never fetched a bundle from this workspace's Metro -- usually the expo-dev-client server picker waiting for a tap (it lists EVERY Metro on the machine; tapping another workspace's row loads the wrong project's bundle), or iOS 26 gating the deep link behind an "Open in <app>?" alert -- which on a fresh simulator appears on EVERY first launch. The stderr warning is a numbered list of actions in the order that resolves it: confirm the alert with your device tool FIRST (re-sending the deep link only re-raises it), then the picker -- tap THIS workspace's port from the facts, never a row by memory -- and only with no alert showing, retry thesimctl openurlcommand it prints. On Android there is no alert, so the list leads with the deep link instead:androidreads the app's scheme out of the APK it just installed and opens<scheme>://expo-development-client/?url=http%3A%2F%2F10.0.2.2%3A<port>(the payload'sdevClientUrl), and re-sending that exactam startis the fix. Thewiredline and the payload'sdebugHttpHostsay whether the app's own SharedPreferences were pointed at your port as well, or whether only theadb reverseis carrying it.logs --errorsprinted nothing and exited 0. That is the pass condition, not a broken query. (One record is demoted so this stays true: the dev-client deep linkios/androidopen lands in the app as a link React Navigation has no route for, and it loggedThe action 'NAVIGATE' with payload {"name":"expo-development-client"...} was not handled by any navigatorat error on every healthy cold launch. That exact shape is recorded at info; a real unhandled NAVIGATE names a route your app has and still reports.) It reports errors and fatals since the last marker (written when a bundle attempt finishes -- success or failure -- and when a launch finishes), so a failure you already fixed stops being reported, and when bundles fail back to back only the newest attempt's errors are reported. An empty timeline is different from a clean one: nothing is captured from a bundler you started yourself, and in an Expo project client logs land in the bundler stream rather than under--source client.- The crash never reached JS.
--errorson the client stream is empty butnpx rn-iso logs --source deviceis not -- that is thesimctl log stream/logcatcollectorios/androidattached after launch. - Don't reach for
--forceon a refusal -- a refusal means something is genuinely unexpected, and the message names what. npx rn-iso statusanswers "is my dev server up, which device is mine, did the last build hit the cache, how many errors since it" in one call.
Differences from react-native-worktree
react-native-worktree shares one simulator across worktrees with a mutex. rn-iso gives each environment its own owned, disposable simulator/emulator -- no locking, no contention, and it's destroyed with the environment. If both are installed, prefer rn-iso unless the user explicitly asks for the shared-sim model.
Original metadata
name: rn-iso
description: The React Native / Expo CLI for AI agents. Each project (or worktree) gets its own owned simulator/emulator, a collision-free Metro port, a supervised dev server (`rn-iso start`), a build/install/launch that installs from a shared fingerprint cache when nothing native changed (`rn-iso ios` / `rn-iso android`), and a queryable log timeline (`rn-iso logs --errors`). Use to spin up a worktree, get a running app on a device that is yours, read the errors a build or a redbox produced, and discover which device to target for UI interactions.
user_invocable: true
Attribution and license
MIT License
Copyright (c) 2026 Janic Duplessis
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.