Start here

Getting started

Requirements

An Apple silicon Mac with Xcode.
Node 24 or newer, with Corepack.
Rust and Cargo from rustup.rs, for the source install below.
pnpm on PATH; with Corepack, corepack enable pnpm provides it.
An Expo app that uses expo-dev-client and pnpm, with a pnpm-lock.yaml.

Setup prepares an iOS simulator. To check on a booted Android emulator instead, see Check a plan.

Install

No QaReN release has been published yet, so the plugin carries no qaren build to download. Install from a develop checkout of the repository:

Clone the checkout and install qaren from it:
Terminal window
```
git clone --branch develop https://github.com/Lykhoyda/rn-dev-agent.git qaren-src
cd qaren-src
bash scripts/install-qaren-from-source.sh
```
The installer builds the runtime tarball, verifies it against a manifest it writes for that build, and unpacks it under ~/.qaren/runtime/<version>/. It prints the installed binary path.
From your app’s root directory, start Claude Code with the checkout’s plugin:
Terminal window
```
claude --plugin-dir <checkout>/packages/qaren-plugin
```
<checkout> is the absolute path of qaren-src.
Run the setup skill:
```
/qaren:setup
```

Where `qaren` lands on PATH

The installer links qaren into a directory on your PATH:

The first of ~/.local/bin, ~/bin, /opt/homebrew/bin and /usr/local/bin that is on PATH, exists and is writable. An earlier IDE or toolchain directory is passed over.
Otherwise, the first writable absolute directory on PATH. Empty and relative entries are skipped.
Otherwise, it links ~/.local/bin/qaren and prints the line to run:
Terminal window
```
export PATH="$HOME/.local/bin:$PATH"
```

It never edits shell startup files. It replaces only a link it made into ~/.qaren/runtime/; any other qaren file in that directory is left alone with a notice. A link problem never fails the install: run qaren by the binary path the installer printed. If an earlier PATH directory already holds another qaren, that one still runs: check command -v qaren, and use the printed path when it differs. Re-run the installer to recover an interrupted install.

What `/qaren:setup` does

Setup runs six steps from the app’s root directory. When a step stops, it gives the one reason and the fix.

CLI. It finds the qaren binary the plugin verifies. Until a release is published it accepts the qaren on PATH when that binary lives under ~/.qaren/runtime/ and its version matches the plugin’s. Otherwise it gives you the source install line above and offers to run it for you.
App. It checks that package.json lists expo and expo-dev-client and that pnpm-lock.yaml exists. It asks before running pnpm install. It reads the bundle identifier and the app’s slug from pnpm exec expo config; when that fails, it asks you for both values rather than guessing.
Config. It writes .qaren/config.yaml:
```
appId: <bundle identifier>
devClientScheme: exp+<slug>
```
exp+<slug> is the scheme expo-dev-client generates. When the app’s config turns that scheme off, setup asks you for the scheme the app registers instead. An existing config is shown next to the detected values and changed only with your consent. See Configuration for every key.
Device. It reads the simulator inventory and never boots, shuts down or erases a simulator itself. With one booted simulator it passes no device flag. With none, it picks the newest available iPhone and passes --boot-device --device <udid>, so qaren boots it under its device lease. With several, it asks you which one.
Smoke plan. It reads the app’s launch path in source, picks a text shown on the first screen, and writes .qaren/plans/smoke.md. This plan needs no TYPESAFE_API_KEY.
Run. It starts the first qaren check detached, because a cold native build can take longer than the host’s command limit, and follows the run until it ends. Within a minute the progress log names the run, and you can watch it in your own terminal with qaren watch <run-id>. It then reports the receipt’s result, run_id and next_action.

On pass, QaReN is set up. If the receipt’s next_action is a qaren cleanup command, teardown was incomplete and setup offers to run it.

First check

Setup writes the smoke plan in this shape, with the text it picked from your first screen:

## QA

### First screen

1. Wait for "<text>" to appear
✓ "<text>"

Run it again yourself from the app’s root directory, on the simulator setup used:

qaren check --plan-file .qaren/plans/smoke.md --device <udid> --json

<udid> is the simulator setup chose or booted. With exactly one booted simulator you can leave --device <udid> out; with several, qaren check refuses without it.

Follow it from a second terminal:

qaren watch --latest

Next, write a plan for a feature, or ask the using-qaren skill to write one.