# native-sim

> Stream a live iOS Simulator of your React Native or Expo app from a GitHub-hosted macOS runner to your browser — and let a coding agent drive it.

Install with `npm i -g native-sim`. Needs `gh` authenticated, Node 20+, and an
`expo` dependency in package.json. Public repos get unlimited free Actions
minutes, which is what makes this viable.

## Start here

- [Usage skill](https://reactnativefeel.com/sim/skill.md): the full operating guide for this CLI — commands,
  timings, and the gotchas that cost real debugging time. Save it as
  `.claude/skills/native-sim/SKILL.md` in the repo you are working in (or
  `.agents/skills/`, or paste it into context).

## Quick start

```sh
cd my-expo-app
native-sim up --public --minutes 60      # push, build, stream; prints the URL
native-sim up --app <url> --public       # install an already-built simulator .app;
                                      # no source is pushed to the repo
native-sim status                        # session state + stream URL
native-sim down                          # cancel latest session; stream dies with it
native-sim down --all                    # cancel every run still in flight
native-sim doctor                        # check prerequisites
native-sim r2                            # one-time R2 setup for hosting builds
native-sim upload ./MyApp.app            # -> presigned URL for --app
```

Prerequisites: `gh` authenticated, Node 20+, an `expo` dependency in `package.json`.

## Rules that matter

- **Never build iOS locally.** Offloading the build is the entire point; a local
  `expo prebuild` / `xcodebuild` defeats it. Use `native-sim up --public`, add
  `--export` to pull the finished archive down, or `--app <url>` to skip compiling.
- **`--public` is not a detail.** Public repos are free and unlimited; private
  macOS minutes bill at $0.062/min with a 10x multiplier.
- The stream URL is published as a **commit status**, the only GitHub surface
  readable while a job is still running.

## Reference

- [CLI reference](https://reactnativefeel.com/sim/docs): generated from the binary's own `--help`.
- [Landing page](https://reactnativefeel.com/sim/): what it is and how the flow works.
- [Source](https://github.com/bidah/native-sim): issues, workflow template, the auth gate.
- Agent control: `native-sim up --public --agent` runs an
  [agent-device](https://agent-device.dev/) proxy on the same tunnel and key, so an
  agent can tap, scroll and read the accessibility tree of the running app.