Agenteract is an experimental bridge that lets large-language-model agents see and interact with running applications — starting with React Native / Expo and Gemini CLI.

First, install the Agenteract CLI. This tool manages communication between the AI agent and your local development servers.

npm install -g @agenteract/cli

Next, install the appropriate package for your project type:

For React Native (Expo):

npm install @agenteract/expo

For React (Vite):

npm install @agenteract/react

Install AGENTS.md to allow your coding assistant to understand how Agenteract works. If you already have an AGENTS.md file, the contents will be appended.

npx @agenteract/agents md creates AGENTS.md

Copy the file to a specific agent name if required:

cp AGENTS.md GEMINI.md

Now you can reference the file for your agent in a message, or restart the CLI for it to take effect.

Create an agenteract.config.js file in the root of your project. This file defines which applications Agenteract will manage.

Here is an example configuration for a monorepo containing Expo, Vite, and Swift projects:

// agenteract.config.js
export default {
  /**
   * The port for the central Agenteract server.
   * The agent connects to this port.
   */
  port: 8766,

  /**
   * An array of projects to manage.
   */
  projects: [
    {
      // A unique identifier for this app. Used for targeting commands.
      name: 'expo-app',
      // The path to the app's root directory, relative to this config file.
      path: './examples/expo-example',
      // The type of project. Can be 'expo' or 'vite'.
      type: 'expo',
      // The port for this app's dev server PTY bridge.
      ptyPort: 8790,
    },
    {
      name: 'react-app',
      path: './examples/react-example',
      type: 'vite',
      ptyPort: 8791,
    },
    {
      name: 'swift-app',
      path: './examples/swift-app',
      type: 'native'
    }
  ],
};

The command below will create an initial agenteract.config.js, or add entries to an existing configuration.

npx @agenteract/cli add-config <path> <projectName> <type>

To allow Agenteract to 'see' and interact with your application, you need to add the AgentBridge component to your app's entry point.

For React Native (Expo) - App.tsx:

import { AgentBridge } from '@agenteract/expo';
import { View, Text } from 'react-native';

export default function App() {
  return (
    <View style={{ flex: 1 }}>
      {/* Your existing application */}
      <Text>Welcome to my app!</Text>

      {/* Add the AgentBridge */}
      <AgentBridge />
    </View>
  );
}

For React (Vite) - src/App.tsx:

import { AgentBridge } from '@agenteract/react';

function App() {
  return (
    <>
      {/* Your existing application */}
      <h1>Welcome to my app!</h1>

      {/* Add the AgentBridge */}
      <AgentBridge />
    </>
  );
}

export default App;

For Swift UI

See agenteract-swift

With your configuration in place and your app instrumented, you can now start Agenteract.

Open a terminal and run the following command from the root of your project (where your agenteract.config.js is located):

npx @agenteract/cli dev

This command will:

AI agents can now connect to the Agenteract server using the tools described in AGENTS.md. The agent can view your app's component hierarchy and perform actions like tapping buttons or typing into text fields.

Your agent is now ready to Agenteract!

This guide covers how to set up the local development environment to run the Expo example app and the agent server.

First, clone the repository and ensure you have pnpm installed.

git clone https://github.com/agenteract/agenteract.git
cd agenteract
git submodule update --init --recursive
npm install -g pnpm

Install all dependencies for the monorepo and build the packages from the root directory.

npm install -g pnpm
pnpm install
pnpm build

We need to use linking to work locally:

Usage:

cd packages/server
pnpm link --global
cd packages/agents
pnpm link --global
cd packages/cli
pnpm link --global

Start the Agenteract development environment using the unified CLI:

pnpm agenteract dev

# once published, you can use:
npx @agenteract/cli dev

This will:

The multiplexed output will show logs from all your running applications in a single terminal.

Once the app is running, it will automatically connect to the agent server. You should see connection logs in the multiplexed output.

You can manually simulate an agent command to test the connection:

curl -s -X POST http://localhost:8766/expo-app -d '{"action":"getViewHierarchy"}'

The server will forward this to the app, which responds with a JSON payload of its view hierarchy.

This step creates or appends to your AGENTS.md file. This informs coding agents how to interact with the app.

npx @agenteract/agents md [dest] # You can specific the name, eg GEMINI.md

If you are using a separate agent to your IDE, start it now, otherwise you can use the built in agent (Tested with Cursor, Gemini CLI)

Issue some instructions. You might need to prime the agent the first time

You can use the Get View Hieararchy tool to inspect the current app state.
Add a button that disappears when it is clicked.
Confirm that it works using a simulated action.

Agents should view the current hierarchy, modify the code, view again, simulate a tap, then confirm that the button disappeared by viewing the hierarchy one final time.

Because packages/agents/AGENTS.md contains instructions about how to interact with the app, you don't need to explicitly tell it to use the AgentDebugBridge.

This project uses Jest for testing.

To run the tests for all packages, use the following command from the root directory:

pnpm test

To run the tests for a specific package, use the --filter flag:

pnpm --filter @agenteract/react test

Tests are run automatically on every push and pull request to the main branch using GitHub Actions.

Integration tests verify that packages can be installed and used correctly after publication. They use Verdaccio , a lightweight private npm registry running in Docker.

Local testing workflow:

# Start local npm registry
pnpm verdaccio:start

# Build and publish packages
pnpm verdaccio:publish

# Run integration tests
pnpm test:integration

# Clean up
pnpm verdaccio:stop

GitHub Actions: Integration tests run automatically on PRs and pushes to main and release/** branches using Verdaccio as a service container.

Authentication: Uses expect to automate the authentication process. See docs/VERDACCIO_AUTH.md for details.

See docs/INTEGRATION_TESTING.md for complete information.