react-native-ai-devtools-sdk

execbro-sdk

Companion SDK for ExecBro — captures network requests, console logs, and state store references from your React Native app for AI-powered debugging. Ships as the npm package execbro-sdk, pairs with the MCP server execbro. Legacy react-native-ai-devtools-sdk keeps receiving identical builds via mirror-publish.

Why use this SDK?

The ExecBro MCP server (npm: execbro) connects to your app via Chrome DevTools Protocol (CDP). This works great for most features, but CDP has limitations on newer React Native architectures (Expo SDK 52+, Bridgeless):

	Without SDK	With SDK
Startup network requests (auth, config)	Missed	Captured from first fetch
Request/response headers	Partial	Full
Request/response bodies	Not available	Full (including GraphQL)
Console logs from startup	May miss early logs	Captured from first log
State store access	Manual via execute_in_app	Direct references exposed
Works on Bridgeless (Expo SDK 52+)	Partial	Full
Setup	None	One import

The SDK patches fetch and console at import time and stores everything in an in-app buffer. The MCP server automatically detects the SDK and reads from it — no extra configuration needed.

Installation

npm install execbro-sdk

Legacy package name

This SDK was previously published as react-native-ai-devtools-sdk. The legacy name continues to receive identical builds via mirror-publish — existing installations keep working. New installs should use execbro-sdk.

Setup

Add to your app's entry file (index.js, App.tsx, or app/_layout.tsx for Expo Router) — must be the first import:

import { init } from 'execbro-sdk';
if (__DEV__) {
  init();
}

// ... rest of your imports

That's it. The MCP tools (get_network_requests, get_logs, etc.) will automatically use the SDK data when available.

With state stores

Pass references to your state management stores for direct AI access:

import { init } from 'execbro-sdk';
import { store } from './store'; // Redux store
import { queryClient } from './queryClient'; // TanStack Query

if (__DEV__) {
  init({
    stores: {
      redux: store,
      queryClient: queryClient,
    },
  });
}

The AI assistant can then inspect store state directly:

execute_in_app with expression="globalThis.__RN_AI_DEVTOOLS__.stores.redux.getState()"

With navigation

Pass your navigation reference for AI-powered navigation inspection:

import { init } from 'execbro-sdk';
import { navigationRef } from './navigation';

if (__DEV__) {
  init({
    navigation: navigationRef,
  });
}

With custom references

Use custom to expose any additional tools, services, or objects that don't belong to stores or navigation (e.g. AsyncStorage, MMKV, analytics):

import { init } from 'execbro-sdk';
import AsyncStorage from '@react-native-async-storage/async-storage';
import { storage } from './mmkv';

if (__DEV__) {
  init({
    custom: {
      asyncStorage: AsyncStorage,
      mmkv: storage,
    },
  });
}

Configuration options

init({
  // Max network entries to buffer (default: 500)
  maxNetworkEntries: 500,

  // Max console entries to buffer (default: 500)
  maxConsoleEntries: 500,

  // Max flowpoint entries to buffer (default: 500)
  maxFlowpointEntries: 500,

  // State store references for AI access
  stores: {
    redux: reduxStore,
    queryClient: queryClient,
    userStore: useUserStore,
  },

  // Navigation reference
  navigation: navigationRef,

  // Any additional references for AI access
  custom: {
    asyncStorage: AsyncStorage,
    mmkv: storage,
  },
});

Flowpoints — instrument and verify flows

flowpoint() drops structured, timestamped breadcrumbs grouped by flow, so an AI agent (via the ExecBro MCP tools get_flowpoints, wait_for_flowpoint, verify_flow) can verify what actually happened inside a flow instead of inferring it from console logs.

import { flowpoint } from "execbro-sdk";

async function addToCart(item) {
    flowpoint({ name: "add-to-cart", step: "start", begin: true });
    await clearCart();
    flowpoint({ name: "add-to-cart", step: "cleared", meta: { removed: 3 } });
    try {
        await addItem(item);
        flowpoint({ name: "add-to-cart", step: "item-added" });
    } catch (e) {
        flowpoint({ name: "add-to-cart", step: "failed", meta: { reason: e.message }, level: "error" });
    }
}

• name — the flow (grouping key, keep it stable and low-cardinality)
• step — the point within the flow (what verification asserts against)
• meta — optional free-form payload (object, string, anything JSON-ish)
• level — 'info' (default) | 'warn' | 'error'
• begin: true — marks a new run of the flow, separating repeated attempts

Safe to leave in your code: like everything else in this SDK, flowpoint() is a silent no-op in production builds and costs nothing.

How it works

Architecture

React Native App
  |
  |  1. import { init } from 'execbro-sdk'
  |     → patches globalThis.fetch (captures all network requests)
  |     → patches console.log/warn/error/info/debug (captures all logs)
  |     → stores references to state management stores
  |     → exposes globalThis.__RN_AI_DEVTOOLS__ with query methods
  |
  |  2. App runs normally — all fetch() calls and console output
  |     are intercepted, stored in circular buffers, and passed
  |     through to their original implementations unchanged
  |
  v
ExecBro MCP Server (npm: execbro)
  |
  |  3. Connects to app via CDP (Chrome DevTools Protocol)
  |     Detects SDK: typeof globalThis.__RN_AI_DEVTOOLS__?.getNetworkEntries === "function"
  |
  |  4. MCP tools read SDK data via Runtime.evaluate:
  |     get_network_requests → globalThis.__RN_AI_DEVTOOLS__.getNetworkEntries()
  |     get_logs             → globalThis.__RN_AI_DEVTOOLS__.getConsoleEntries()
  |
  v
AI Assistant (Claude Code, Cursor, VS Code Copilot, etc.)

What gets captured

Network requests — Every fetch() call is intercepted. The SDK captures:

• Method, URL, status, statusText, duration
• Full request and response headers
• Full request and response bodies (via response.clone().text() — the original response is untouched)
• Errors and timing

Console output — Every console.log/warn/error/info/debug call is captured with:

• Log level, timestamp, formatted message
• Original console methods still work — logs appear in Xcode/Metro/DevTools as normal

State stores — References passed via stores option are exposed globally for the MCP server to query on demand.

Why it must be the first import

The SDK patches globalThis.fetch and console when init() is called. If other code (your app, libraries like Apollo/Axios) calls fetch before the SDK patches it, those requests won't be captured. Placing the import first ensures the SDK intercepts everything from the very beginning, including:

• OAuth token refresh on app launch
• Initial GraphQL/REST API calls
• Config/feature flag fetches
• Early console output during initialization

Production safety

The SDK is a no-op in production builds:

• The if (__DEV__) guard in your code prevents init() from being called
• Even if called without the guard, init() checks __DEV__ internally as a safety net
• Tree-shaking removes the SDK code from production bundles when wrapped in if (__DEV__)

Circular buffers

Both network and console data are stored in circular buffers (default: 500 entries each). When the buffer is full, the oldest entries are evicted. This bounds memory usage regardless of how many requests or logs the app produces.

Exposed global API

The SDK exposes globalThis.__RN_AI_DEVTOOLS__ with these methods. You don't need to call these directly — the MCP tools use them automatically.

globalThis.__RN_AI_DEVTOOLS__ = {
  version: '0.5.1',

  // Capabilities — tells MCP server what's available
  capabilities: {
    network: true,
    console: true,
    stores: true,      // true if stores were passed
    navigation: true,  // true if navigation was passed
    flowpoints: true,
    render: false,     // future: render profiling
  },

  // State store references
  stores: { redux: store, queryClient: qc, ... },

  // Navigation reference
  navigation: navigationRef,

  // Custom references (AsyncStorage, MMKV, etc.)
  custom: { asyncStorage: AsyncStorage, mmkv: storage, ... },

  // Network
  getNetworkEntries(),  // all buffered network entries (incl. headers + bodies)
  clearNetwork(),       // returns number of entries cleared

  // Console
  getConsoleEntries(),  // all buffered console entries
  clearConsole(),       // returns number of entries cleared

  // Flowpoints
  addFlowpoint(options),     // used by the flowpoint() helper
  getFlowpointEntries(),     // all buffered flowpoints
  getFlowpointSnapshot(),    // { contextId, entries } — used by the MCP drain
  clearFlowpoints(),         // returns number of entries cleared
}

Compatibility

React Native	Architecture	Status
Expo SDK 54+ (RN 0.79+)	Bridgeless	Fully supported
Expo SDK 52-53 (RN 0.76-0.78)	Bridgeless	Fully supported
RN 0.73-0.75	Hermes + Bridge	Fully supported
RN 0.70-0.72	Hermes + Bridge	Should work (untested)
RN < 0.70	JSC	Not tested

The SDK has zero native dependencies — it's pure JavaScript that patches standard globals (fetch, console). It works on any React Native version that supports these globals.

Relationship to ExecBro

This SDK is an optional companion to the ExecBro MCP server (npm: execbro). The MCP server works without the SDK — it connects via CDP and provides console logs, component inspection, UI interaction, and basic network tracking out of the box.

The SDK enhances network and console capture for cases where CDP alone isn't sufficient (Bridgeless architecture, startup request capture, response bodies). When the MCP server detects the SDK, it automatically prefers SDK data. When the SDK is absent, it falls back to CDP.

You do NOT need the SDK for:

• Console log viewing (get_logs)
• Component tree inspection (get_component_tree, inspect_component)
• UI interaction (tap, swipe, screenshots)
• JavaScript execution (execute_in_app)
• App reload, bundle error detection, device management

The SDK improves:

• Network request capture (especially startup requests and response bodies)
• Console log capture (startup logs that CDP might miss)
• State store access (direct references vs manual global inspection)

License

MIT