---
name: ansight-install-react-native
description: Use this skill when installing or configuring Ansight in a React Native iOS and Android app. Add @ansight/react-native, run native install steps, initialize the JavaScript bridge, infer Studio registration metadata from native projects, register the app in Studio, issue a signed pairing config, wire developer pairing through developer-only JavaScript or native build configuration, ask which remote-tool profile to enable through ToolGuard (all developer-time tools by default, selected tools, or none), keep `reflect.*` reflection tools as development-time dependencies by default, disable tools outside the developer guard, configure platform permissions, install or recommend the ansight-app-inspection-react-native skill, create ansight-readme.md, and verify both platform builds.
---

# Ansight React Native Install Skill

Use this skill when a user asks an AI agent to install or configure Ansight for a React Native app that builds native iOS and Android projects.

Do not use this skill for native-only iOS, native-only Android, .NET, Flutter, server, desktop, or web-only projects.

## Goal

Produce a working React Native Ansight integration for local developer workflows, register the app with Studio, issue a signed pairing config, ask which remote tools should be available, enable the chosen tools only behind the app's developer guard, disable tools for production builds, configure or recommend the companion React Native app-inspection skill, create `ansight-readme.md`, verify JavaScript and native builds where practical, and explain remaining app UI or Studio steps.

## Package Defaults

Install the React Native bridge:

```bash
npm install @ansight/react-native
```

Published package: [`@ansight/react-native`](https://www.npmjs.com/package/@ansight/react-native).

Use the package manager already used by the app. After install, rebuild native projects so autolinking applies:

```bash
npx pod-install
npx react-native run-ios
npx react-native run-android
```

This bridge expects matching native SDK packages:

- CocoaPods: [`Ansight`](https://cocoapods.org/pods/Ansight) and [`AnsightObjC`](https://cocoapods.org/pods/AnsightObjC) version `1.0.2-preview.1`
- Maven: [`ai.ansight:ansight-android`](https://central.sonatype.com/artifact/ai.ansight/ansight-android) version `1.0.2-preview.1`

React Native iOS uses CocoaPods through autolinking for this package. Do not try to replace that with SwiftPM unless the user is intentionally changing the package's native integration.

Native reflection exposes `reflect.*` through the selected remote-tool profile. Default `withReflectionTools(...)` and the underlying native reflection suites to `__DEV__`, Debug, or explicit local-development builds only. Do not enable `reflect.*` for production bundles or distributable native variants without explicit user approval and matching runtime guards.

## Inputs To Confirm

- package manager: npm, yarn, pnpm, or Expo-managed workflow constraints
- React Native app entry point and where async bootstrap code belongs
- iOS bundle identifier and Android application id
- whether both platforms should be configured now
- whether the app has an existing debug menu, settings row, hidden gesture, or developer screen for pairing
- remote-tool setup profile: all developer-time tools, selected tools, or none. Present all developer-time tools as the default unless the user already specified a narrower policy
- for selected tools, confirm the native suites, React inspection options, custom tools, and guard level required by the workflow
- whether QR pairing, screen views, lifecycle events, custom logs, JPEG session capture, or non-default tool options are requested
- Studio registration metadata only if it cannot be inferred
- pairing config duration, defaulting to `7d` or a short local-development duration when unspecified

## Required Constraints

- preserve existing package manager, Metro, app bootstrap, navigation, native project, and build patterns
- keep generated pairing JSON out of source control
- infer Studio metadata from native projects before asking the user
- use Studio MCP tools for app registration and pairing config issuance when available
- do not hand-author signed pairing configs
- ask the user which remote-tool profile to configure unless the request already specifies it. Offer: all developer-time tools, selected tools, or none
- default to all developer-time tools when the user accepts defaults: enable them only when `__DEV__` or the app's equivalent development-only condition is true
- default `reflect.*` reflection tools to development-time JavaScript/native configuration and guards
- disable tool discovery and execution with `withToolsDisabled()` when the development-only condition is false
- for selected tools, use the narrowest guard that supports the requested workflow: `withReadOnlyToolAccess()`, `withReadWriteToolAccess()`, or `withAllToolAccess()`
- for no remote tools, keep pairing and telemetry setup possible but call `withToolsDisabled()` in both developer and production paths
- add QR scanning only when requested or when an existing scanner/debug flow is identified
- do not print full pairing JSON, one-time tokens, or compact pairing codes in the final response unless explicitly requested

## Workflow

1. Identify the React Native app root, package manager, app entry point, iOS project, Android app module, bundle identifier, application id, and display names.
2. Check whether `@ansight/react-native` is already installed by inspecting `package.json`, lockfiles, imports, `Podfile.lock`, and Android Gradle outputs.
3. Ask which remote-tool profile to configure unless the user already specified one:
   - all developer-time tools: default, enables supported native and React tools under `__DEV__`, disables tools otherwise
   - selected tools: enables only requested suites/options with the narrowest matching guard
   - none: keeps tools disabled even in developer builds
4. Infer Studio metadata:
   - `appId`: prefer a stable shared id when iOS and Android are intended to be one Studio app; otherwise use the platform id being configured
   - `appName`: iOS display name, Android label, Expo name, package name, or project name
   - `codebasePath`: nearest repo root
   - icon: iOS asset catalog or Android launcher icon source when available
5. Ensure pairing artifacts are ignored by source control:
   - `ansight.json`
   - `*.ans.json`
   - `ansight.developer-pairing.json`
   - `.env.local`
6. Add `@ansight/react-native` with the existing package manager.
7. Run or note required native install steps, including `npx pod-install` for iOS.
8. Register the app with Studio and issue a signed pairing config through MCP.
9. Save the returned `configJson` to a local ignored file. Prefer a developer-only native build value or local environment value over committing JSON into JavaScript.
10. Initialize Ansight from the React Native app bootstrap.
11. Configure the requested remote-tool profile through the builder and tool guard. Always call `withToolsDisabled()` outside the developer guard.
12. Configure iOS and Android permissions required by the selected pairing path.
13. Add QR pairing or custom tools only when requested.
14. Add or recommend the `ansight-app-inspection-react-native` skill.
15. Create `ansight-readme.md`.
16. Run JavaScript checks and native builds where practical, then report changed files, Studio ids, local config path, and remaining manual steps.

## Runtime Setup

Initialize once during app startup before trying to connect:

```ts
import Ansight from "@ansight/react-native";

type RemoteToolProfile = "all" | "selected" | "none";

const isDevelopmentOnly = __DEV__;
const remoteToolProfile: RemoteToolProfile = "all";
const appId = "com.example.app";

export async function initializeAnsight(pairingJson?: string) {
  const builder = Ansight.createOptionsBuilder();

  if (isDevelopmentOnly) {
    builder
      .withNativeAllInOneDefaults()
      .withSessionJpegCapture(2000, 60, 480);

    if (pairingJson) {
      builder.withBundledHostConnection({
        bundledDeveloperConfigJson: pairingJson,
      });
    }

    configureDeveloperRemoteTools(builder, remoteToolProfile);
  } else {
    builder.withToolsDisabled();
  }

  await Ansight.initializeAndActivate(builder.build());

  if (isDevelopmentOnly && remoteToolProfile === "all") {
    const reactTools = Ansight.installReactTools({
      includeBounds: true,
      includeProps: true,
      includeState: true,
      maxDepth: 60,
      maxNodes: 5000,
      enableActions: true,
    });
    await reactTools.ready;
  }
}

function configureDeveloperRemoteTools(
  builder: ReturnType<typeof Ansight.createOptionsBuilder>,
  profile: RemoteToolProfile,
) {
  if (profile === "none") {
    builder.withToolsDisabled();
    return;
  }

  if (profile === "selected") {
    builder
      .withReadOnlyToolAccess()
      .withVisualTreeTools()
      .withDatabaseTools({ includePlatformRoots: true });
    return;
  }

  builder
    .withAllToolAccess()
    .withRemoteTools({
      secureStorage: {
        appleService: appId,
        preferencesName: appId,
      },
    })
    .withVisualTreeTools()
    .withFileSystemTools()
    .withDatabaseTools({ includePlatformRoots: true })
    .withPreferencesTools()
    .withReflectionTools({ includeBuiltInRoots: true });
}
```

Connect after initialization:

```ts
await Ansight.connect(null, {
  clientName: "React Native App",
  expectedAppId: "com.example.app",
});
```

## Native And React Tools

Remote tools are controlled by both registered suites and the active `ToolGuard`. Ask the user which profile to wire:

| Profile | Developer builds | Production or non-dev builds |
| --- | --- | --- |
| all developer-time tools | `withAllToolAccess()`, supported native suites, and React inspection/actions | `withToolsDisabled()` |
| selected tools | requested suites only, with the narrowest matching guard | `withToolsDisabled()` |
| none | `withToolsDisabled()` | `withToolsDisabled()` |

Native FileSystem, Database, Preferences, Reflection, and SecureStorage suites are configured through `remoteTools` or suite helpers. Native VisualTree is included in the default all-tools profile and can also be selected explicitly:

```ts
await Ansight.initializeAndActivate(
  Ansight.createOptionsBuilder()
    .withReadOnlyToolAccess()
    .withVisualTreeTools()
    .withDatabaseTools({ includePlatformRoots: true })
    .build(),
);
```

React inspection tools are separate from native VisualTree. In the all-tools profile, install React inspection with props, state, bounds, and actions for developer builds. In the selected-tools profile, add only the React inspection options the user requested.

## Platform Permissions

iOS local network pairing or host discovery requires:

```xml
<key>NSLocalNetworkUsageDescription</key>
<string>Ansight client needs local network access to discover and connect to the host test harness.</string>
```

Android host connection requires:

```xml
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
```

Add camera permissions and runtime prompts only when QR pairing is exposed. Do not add broad cleartext or network settings by default.

## Studio Registration And Pairing

Use the Ansight Studio MCP tools when available:

```json
{
  "name": "ansight_register_app",
  "arguments": {
    "appId": "INFERRED_APP_ID",
    "appName": "INFERRED_APP_NAME",
    "codebasePath": "/absolute/path/to/repo"
  }
}
```

```json
{
  "name": "ansight_issue_pairing_config",
  "arguments": {
    "appId": "INFERRED_APP_ID",
    "appName": "INFERRED_APP_NAME",
    "duration": "7d"
  }
}
```

Save the returned `configJson` locally. Do not commit it. Prefer the stdio bridge `ansight-daemon mcp-stdio` for future agent access.

## Agent Inspection Skill

Install or recommend:

```text
https://www.ansight.ai/skills/react-native/ansight-app-inspection-react-native.md
```

Do not claim it was installed unless the agent configuration was actually updated.

## ansight-readme.md

Create `ansight-readme.md` near the app root:

```markdown
# Ansight React Native Pairing Notes

- App id: `REPLACE_WITH_STUDIO_APP_ID`
- iOS bundle id: `REPLACE_WITH_IOS_BUNDLE_IDENTIFIER`
- Android application id: `REPLACE_WITH_ANDROID_APPLICATION_ID`
- App name: `REPLACE_WITH_APP_NAME`
- Local pairing config: `REPLACE_WITH_LOCAL_ANSIGHT_JSON_PATH`
- Dependency: `@ansight/react-native`
- Remote tool profile: `REPLACE_WITH_ALL_SELECTED_OR_NONE`
- Reflection tools: `reflect.*`, development-time dependency by default
- Runtime guard: chosen profile when the app's development-only condition is true, disabled otherwise
- Recommended agent skill: `https://www.ansight.ai/skills/react-native/ansight-app-inspection-react-native.md`

## Pairing

1. Open Ansight Studio.
2. Select this app.
3. Issue or select a pairing config.
4. Launch the React Native app with the app's development-only condition enabled.
5. If automatic bundled developer pairing is configured, the app can connect from the bundled config.
6. If QR pairing is required, wire a developer-only app UI entry point before using it.
7. Remote tools follow the documented profile and are disabled outside the development-only guard.
```

## Verification

Run the relevant checks:

```bash
npm test
npm run typecheck
npx pod-install
npx react-native run-ios
npx react-native run-android
```

Use the actual package-manager commands from the app when they differ.

Done criteria:

- JavaScript package is installed with the app's package manager
- iOS pods are installed when configuring iOS
- Android Gradle sync/build sees the autolinked module when configuring Android
- app initializes Ansight once from React Native startup
- remote-tool profile was asked for or supplied, implemented, and documented
- non-developer runtime guard disables tools
- developer runtime guard matches the selected remote-tool profile
- local pairing config exists and is ignored
- native permissions match the selected pairing path
- Studio app registration and pairing config were created
- `ansight-readme.md` documents remaining pairing UI work
- final response lists changed files, app id, pairing config id/expiry, verification commands, and remaining manual steps