react-native-agentkit

Let AI agents control your React Native app. Wrap your app with <AgentKitProvider>, and the library automatically discovers all interactive UI elements and exposes them through a command interface — enabling any AI agent to observe, interact, and test your app autonomously.

Features

• 🔍 Auto-Discovery — Automatically finds buttons, inputs, switches, scrollviews, and more
• 🤖 AI-Native — Purpose-built for LLM agents (Claude, GPT, Gemini, etc.)
• 📱 Device Management — Agents can boot simulators, install apps, and grant permissions autonomously
• 🧪 Natural Language Tests — Write test cases in plain English, agents execute them
• 🔌 Zero Config — Drop in <AgentKitProvider> and you're ready
• 🌐 Cloud Relay — Control apps remotely through a WebSocket relay server
• 🛡️ Dialog Interception — Automatically handles native alerts and permission prompts

Installation

npm install react-native-agentkit
# or
yarn add react-native-agentkit

Quick Start

1. Wrap your app

import { AgentKitProvider } from 'react-native-agentkit';

export default function App() {
  return (
    <AgentKitProvider debug={__DEV__} relayUrl="ws://localhost:8347">
      <YourApp />
    </AgentKitProvider>
  );
}

2. Start the relay server

npx react-native-agentkit-relay
# Listening on port 8347

3. Control via CLI

# Interactive REPL
npx react-native-agentkit connect --relay=ws://localhost:8347

# Execute single commands
npx react-native-agentkit exec list --relay=ws://localhost:8347
npx react-native-agentkit exec tap submit-btn --relay=ws://localhost:8347

# Pipe mode for AI agents
echo '{"cmd":"list"}' | npx react-native-agentkit pipe --relay=ws://localhost:8347

Commands

| Command | Description | Example | | ---------- | ----------------------------- | ----------------------------------------------------------------- | | list | List all interactive elements | {"cmd": "list"} | | tap | Tap an element | {"cmd": "tap", "target": "submit-btn"} | | toggle | Toggle a switch/checkbox | {"cmd": "toggle", "target": "agree-switch"} | | setValue | Set slider/numeric value | {"cmd": "setValue", "target": "brightness", "value": 75} | | type | Type text into input | {"cmd": "type", "target": "email", "text": "[email protected]"} | | clear | Clear input text | {"cmd": "clear", "target": "email"} | | scroll | Scroll a view | {"cmd": "scroll", "target": "main-scroll", "direction": "down"} | | swipe | Swipe an element | {"cmd": "swipe", "target": "item-1", "direction": "left"} | | read | Read element value | {"cmd": "read", "target": "header"} | | state | Full screen state snapshot | {"cmd": "state"} | | find | Search elements by text | {"cmd": "find", "filterText": "login"} | | back | Navigate back | {"cmd": "back"} | | wait | Wait for element to appear | {"cmd": "wait", "target": "success-msg", "timeout": 5000} | | ping | Check connection | {"cmd": "ping"} |

Response Format

All commands return structured JSON with optional screen state:

{
  "success": true,
  "command": "tap",
  "target": "submit-btn",
  "result": { "elementTapped": true },
  "screenState": { "elements": [...], "count": 5 },
  "timestamp": 1710000000000
}

Test Cases

Write test cases as natural language instructions that AI agents execute autonomously:

const { describe, it, beforeEach } = require('react-native-agentkit/test');

module.exports = describe('Shopping Cart', () => {

  beforeEach(`
    Make sure we're on the Products page
  `);

  it('should add item to cart', `
    Tap on the first product
    Tap the "Add to Cart" button
    The cart badge should show "1"
    Navigate to the Cart tab
    The product should be listed
  `);

  it('should remove item from cart', `
    Navigate to the Cart tab
    Swipe left on the first cart item
    Tap the delete button
    The cart should be empty
  `);

});

Then tell your AI agent: "I have test cases in the project. Go run them."

📖 Full test cases documentation →

AI Agent Prompts

Copy-paste one of these prompts to give an AI agent (Claude Code, Cursor, etc.) the ability to control your app.

Local Development

You can control the React Native app in this project using `react-native-agentkit`.

First, read the skill file at `node_modules/react-native-agentkit/SKILL.md` —
it contains the complete workflow, all commands, device management, and best practices.

Detect whether this is an Expo or bare React Native project from the project files
(app.json, package.json, etc.) and determine the bundle ID and build configuration
accordingly.

To send commands, use pipe mode:
echo '{"cmd":"state"}' | npx react-native-agentkit pipe --relay=ws://localhost:8347

Follow the instructions in SKILL.md. Now please: [describe what you want the agent to do]

Production / Remote

You can control a React Native app using `react-native-agentkit`.

App details:
- Bundle ID: com.yourcompany.yourapp
- Build path: ./path/to/YourApp.app (or .apk)
- Relay: ws://your-relay-host:8347 --channel=your-channel --secret=your-secret

First, read the skill file at `node_modules/react-native-agentkit/SKILL.md` —
it contains the complete workflow, all commands, device management, and best practices.

To send commands, use pipe mode with authentication:
echo '{"cmd":"state"}' | npx react-native-agentkit pipe --relay=ws://your-relay-host:8347 --channel=your-channel --secret=your-secret

Follow the instructions in SKILL.md. Now please: [describe what you want the agent to do]

Tip: The key is having the agent read SKILL.md first — it teaches the agent the full workflow including pre-flight checks, device setup, permission granting, and UI automation patterns.

Documentation

| Guide | Description | | --- | --- | | Test Cases | Write and run natural language test cases | | Device Management | Boot simulators, install apps, grant permissions | | Production Relay | Cloud relay architecture and authentication | | Hooks & Customization | Custom hooks, manual element registration, props | | Native Dialog Handling | Alert and permission interception |

Running the Example

# 1. Install dependencies
yarn install

# 2. Start the relay server (in a separate terminal)
npx react-native-agentkit-relay

# 3. Start the example app on iOS simulator
cd example
npx expo start --ios

# 4. Connect the CLI (in a separate terminal)
npx react-native-agentkit connect --relay=ws://localhost:8347

# Or execute a single command
npx react-native-agentkit exec list --relay=ws://localhost:8347

License

MIT