Getting started

Requirements

• An Apple silicon Mac with Xcode.
• Node 24 or newer, with Corepack.
• pnpm on PATH; with Corepack, corepack enable pnpm provides it; see launcher compatibility for Corepack and bootstrap shims.
• An Expo app that uses expo-dev-client and pnpm, with a pnpm-lock.yaml.

QaReN 2.0 supports iOS simulators on Apple silicon.

Install

Choose one of three options. Your agent can prepare the prerequisites above, or you can install the plugin yourself if they are already available.

Ask your agent to install (recommended)

Open Claude Code, Codex or Cursor in your app. Other agents are untested. Copy this prompt using the copy button in the code block, then paste it into your agent:

Set up QaReN in this app, from the app root, for my current host (Claude Code, Codex or Cursor). The QaReN repository is https://github.com/Lykhoyda/QaReN.

Check that this is an Apple silicon Mac and a pnpm Expo app using expo-dev-client with pnpm-lock.yaml. Install missing Node 24 or newer, Corepack and pnpm using user-writable locations. Check that full Xcode and an iOS simulator runtime are installed and ready. If a prerequisite needs administrator access, a license agreement or a manual download, stop and tell me the exact step I need to complete. Do not use sudo.

Install the QaReN plugin for my host using the per-host instructions at https://github.com/Lykhoyda/QaReN#install-the-plugin-yourself
If the host needs a plugin UI step or a session restart, tell me what to do and resume setup once the plugin is available.

Run /qaren:setup; if slash commands are unavailable, load and follow the plugin's setup skill. It owns installing the matching qaren CLI, running qaren doctor, configuring this app and selecting the iOS simulator. Follow its source-install fallback only if the release is unavailable. Use the matching binary path it resolves; preserve any existing qaren command on PATH and keep the default QaReN home and installer options.

Follow setup through writing .qaren/plans/smoke.md and running the first smoke check. Read the receipt and report result, run_id and next_action. If setup or the check stops, report the exact reason and fix; do not claim success before a passing receipt.

The agent may need you to complete an Xcode download, accept its license, install an iOS simulator runtime or finish a host's plugin UI step before it can continue.

Install without the prompt

Install the plugin yourself

Use the commands for your host:

# Claude Code
claude plugin marketplace add Lykhoyda/QaReN
claude plugin install qaren@qaren
# Codex
codex plugin marketplace add Lykhoyda/QaReN
codex plugin add qaren@qaren
# Cursor: add the marketplace, then install qaren from /plugin > Marketplace in
# cursor-agent, or from Customize > Plugins in the editor
cursor-agent plugin marketplace add https://github.com/Lykhoyda/QaReN

Then run /qaren:setup from your app's root. In Codex or Cursor, you can ask the agent to set up QaReN using the installed setup skill. Setup installs the matching CLI and runs the first smoke check; see what setup does.

Install from source

This option also needs Rust and Cargo from rustup.rs.

For an unreleased build or when the matching release asset is unavailable, install from a checkout of the repository:

Where qaren lands on PATH

Follow the installation contract for PATH selection, existing-command protection and interrupted-install recovery. Use the binary path the installer prints and keep its default options.

Run a release and a source build side by side

Follow release and source builds side by side for source versioning, state lookup and shared device locks.

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.

1. CLI. It verifies or installs the plugin's matching qaren runtime; follow the installation contract for verification, PATH linking and the source fallback.

2. 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.

3. Config. It writes .qaren/config.yaml:

   yamlCopy

   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.

4. 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.

5. 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.

6. 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 a pass receipt's next_action is a qaren cleanup command, teardown was incomplete and setup offers to run it.

First check

Setup already ran the smoke plan. Now ask your agent to QA something you changed, for example "QA the onboarding change". It writes the plan, runs it and reports the result.