---
name: pixie-setup
description: Use when asked to install, set up, wire up, or onboard react-native-pixie (or "pixie") in a React Native / Expo app, including Claude Code, Cursor, or Codex / MCP integration.
---

# Installing react-native-pixie

Agent playbook. Follow the steps in order; each is idempotent — check before
writing. Do not invent flags, config plugins, or commands not listed here.
Leave all changes uncommitted for the developer to review.

## Facts that override your instincts

- `react-native-view-shot` ships as pixie's own dependency. **Never install
  it separately** — a second direct dep can resolve a different version.
- Pixie has **no Expo config plugin**. Nothing goes in app.json.
- Pixie boots fine without the view-shot native module — screenshots degrade
  gracefully until the next native rebuild. Don't block install on a rebuild.
- The bridge daemon auto-starts with your agent session (Claude Code, Cursor,
  or Codex); there is no daemon command to add anywhere.

## Steps

1. **Locate the app workspace** (the package.json with `react-native`).
   In a monorepo that is `apps/<app>`, not the root. ALL commands below run
   from the app directory unless stated.

2. **Install** — from the app dir: `yarn add -D react-native-pixie`
   (or `npm i -D react-native-pixie`, matching the repo's package manager).

3. **Lockfile-drift check (do not skip).**
   `git diff <lockfile> | grep -E '^[+-]"?(react-native-reanimated|react-native-worklets)'`
   If versions moved, restore them (`git checkout <lockfile>` + re-add, or pin
   exact versions). Drifted reanimated crashes the app at boot with
   `__UI_WORKLET_RUNTIME_HOLDER` errors.

4. **Wrap the app root — only if not already wrapped.** First
   `grep -rn "PixieProvider" <app-root-file>`; skip if present. App root =
   `app/_layout.tsx` (Expo Router) or `App.tsx` (bare). Add:

   ```tsx
   const PixieProvider = __DEV__
     ? require('react-native-pixie').PixieProvider
     : ({ children }: { children: React.ReactNode }) => children
   ```

   and wrap the returned tree: `<PixieProvider>…existing tree…</PixieProvider>`.
   Conditional require, never a static import — release bundles must not
   contain pixie.

5. **Wire the agent side** — from the app dir, pass the agent you are so it
   runs non-interactively: `npx pixie init --agent claude` (or `cursor` /
   `codex`; comma-separate or use `all` for several). Merges into existing
   config, never clobbers. Claude gets `.mcp.json` + `/pixie-watch` + a Stop
   hook; Cursor gets `.cursor/mcp.json` + a rule; Codex gets
   `~/.codex/config.toml` + an `AGENTS.md` section. The cwd matters:
   config and editor-open roots anchor to the directory where the agent runs.

6. **Native rebuild — decide, don't assume.**
   `grep -c RNViewShot ios/Podfile.lock` (or check android config).
   Found → skip. Not found → run the app's native build (`npx expo run:ios`
   or the repo's script) OR, if a build is disruptive now, tell the developer
   screenshots stay off until their next rebuild. Everything else works.

7. **Verify:** `npx pixie status` — every line must be ✅. A missing editor
   CLI line means ↗ Open won't work: have them install their editor's shell
   command (`cursor`/`code`) or set `PIXIE_EDITOR`.

8. **Handoff (required — you cannot do this part).** Your session cannot use
   the MCP server registered during it. Tell the developer exactly:
   1. Run the app (Metro).
   2. Start a NEW agent session in the app directory and begin watching:
      Claude Code → `/pixie-watch`; Cursor → "start pixie watch"; Codex
      (≥ v0.115.0) → "start the pixie watch loop".
   3. In the app: tap the ✎ handle → tap any element → describe → SEND.

## Common mistakes

| Mistake | Reality |
|---|---|
| `expo install react-native-view-shot` | Already a pixie dependency — skip |
| `npx pixie init` at monorepo root | Run where `claude` runs: the app dir |
| Editing `_layout.tsx` blind | Grep for PixieProvider first — may exist |
| Skipping the lockfile diff | The #1 real-world post-install crash |
| Blocking install on a native rebuild | Screenshots degrade; nothing else needs it |
| Ending after `status` passes | Without the `/pixie-watch` handoff the tool is installed but unused |