# ExecBro

[![MCP Registry](https://img.shields.io/badge/MCP_Registry-com.execbro%2Fexecbro-6E56CF)](https://registry.modelcontextprotocol.io/?q=com.execbro%2Fexecbro)

**Give your AI assistant eyes and hands into your running React Native app.** Like Chrome DevTools — but for AI agents.

Build, debug, and verify features end-to-end — without leaving the chat.

ExecBro is the runtime bridge between your AI coding assistant and your running React Native app — exposing MCP tools to read logs and network, inspect component state, capture screenshots, tap the UI, and run JS. Zero config, no SDK or code changes required to start — and installing the [optional SDK](#install-the-sdk-recommended) is recommended for the most robust log and network capture.

<p align="center">
  <img src="https://raw.githubusercontent.com/igorzheludkov/execbro/main/docs/demo/get_logs_demo.gif" alt="ExecBro demo" width="800" />
</p>

## Get started

1. [Setup ExecBro as an MCP server for your agent of choice](#setup)
2. [Setup UI automation helpers](docs/setup.md#ios-simulator--ui-automation-setup)
3. [Install the SDK in your React Native app](#install-the-sdk-recommended) — optional, but recommended for the most robust log, network, and state experience
4. [Authorize and link to the web dashboard](#see-your-usage--execbrocom) — optional, for usage stats and session history
5. Start your React Native app (`npm start` / `expo start`)
6. [Ask your AI assistant](#usage) in plain language — e.g. "Connect to the simulator and investigate what caused the error on the screen"

## See your usage — [execbro.com](https://execbro.com)

Log in at **[execbro.com](https://execbro.com)** to see your ExecBro activity rendered back to you: which tools you use most, tool **error rates**, and your **session history** — so you can spot flaky tools, track usage over time, and understand how your agent drives the app across sessions. It's built from the same anonymous telemetry described in [Telemetry & Privacy](#telemetry--privacy), tied to your installation ID.

Linking is only for the dashboard: it attaches your installs to your account so the stats are yours. Nothing in the tooling is gated behind it.

## Features

### Runtime Interaction

- **Console Log Capture** - Capture `console.log`, `warn`, `error`, `info`, `debug` with filtering and search. Note: on a cold start (first app launch), logs emitted before the MCP server connects are missed — subsequent reloads capture everything. Install the optional [SDK](https://www.npmjs.com/package/execbro-sdk) to buffer logs from the very first line of app startup
- **Network Request Tracking** - Monitor HTTP requests/responses with headers, timing, and body content. Like logs, early network requests on cold start may be missed before the connection is established. Install the optional [SDK](https://www.npmjs.com/package/execbro-sdk) for full capture from app startup including request/response bodies
- **Response Mocking** - Replace or tamper with HTTP responses so error paths are reached through the app's real code — the request builder, the error branch, the retry — instead of being faked by writing state directly. Simulate offline, delay responses, fail only the first attempt to test a retry, or re-issue a captured request with one field changed. Rules survive reload, and altered traffic is always tagged. See the [mocking tutorial](docs/network-mocking.md)
- **JavaScript Execution** - Run code directly in your app (REPL-style) and inspect results
- **Global State Debugging** - Discover and inspect Apollo Client, Redux stores, Expo Router, and custom globals. Wire stores and other app internals straight into the agent with the optional [SDK](#install-the-sdk-recommended) for direct, reliable state access
- **Bundle Error Detection** - Get Metro bundler errors and compilation issues with file locations
- **Tap-to-Source** - Point at any element with RN's Element Inspector and get back the absolute source file and line where it is rendered, resolved from the React fiber's `_debugStack` via Metro symbolication. Works on React 19, where `_debugSource` no longer exists. Selections are buffered in the background, so taps you make during a manual inspector session are captured without asking the agent first

### Device Control

- **iOS Simulator** - Screenshots, app management, URL handling, boot/terminate (via simctl)
- **Android Devices** - Screenshots, app install/launch, package management (via ADB)
- **Unified Tap** - Single `tap` tool with automatic fallback chain: fiber tree → accessibility → OCR → coordinates. Auto-detects platform, accepts coordinates from screenshots and layout tools unchanged. Returns post-tap screenshot and verifies visual change by default
- **Unified Swipe** - Single `swipe` tool that auto-routes to iOS or Android based on the connected device. Takes coordinates in the same screen space as the layout tools and screenshots — no conversion — and returns a `verification.meaningful` signal so agents detect end-of-list, non-scrollable surfaces, and missed coordinates — and on a screen with no React Native connection it says it could not inspect rather than guessing. Essential for scrolling virtualized lists (FlatList/SectionList) where off-screen items aren't in the fiber tree
- **Real Multi-Touch Pinch** *(Android emulator only — iOS in progress)* - A `pinch` tool that sends two genuine kernel touch contacts through the Android emulator's multi-touch bridge, so it zooms maps, galleries, WebViews, and native views alike — it works below the app, not through React Native. Returns the same `verification.meaningful` signal as `swipe`, and refuses on unsupported targets instead of faking a result
- **UI Automation** - Swipe, long press (`tap` with `duration`, resolving the target by testID/text/component), key events, and text input on both platforms. `input_text` targets a field itself and verifies the write by reading it back; on Bridgeless/Fabric apps `replace:true` overwrites pre-filled values by updating React state through `onChangeText`, so controlled components (Formik, react-hook-form, useState) stay consistent. `native:true` types into whatever the OS reports as focused, with no RN connection needed, and `dismiss_keyboard` operates the same way
- **Accessibility Inspection** - Query UI hierarchy to find elements by text, label, or resource ID
- **OCR Text Extraction** - Extract visible text with tap-ready coordinates via Google Cloud Vision (works on any screen content)

### Credential Safety

- **Secrets never enter the transcript** - Every tool's output passes one redaction chokepoint, so a token is replaced by a handle (`[secret:auth_api.acme.io]`) whether it appears in a network header, a Redux store, a log line or a URL. Credential headers are matched by pattern rather than a fixed list, so vendor-namespaced ones (`x-shopify-access-token`, `x-goog-api-key`, `x-hasura-admin-secret`) are covered too, while `x-request-id` and `x-idempotency-key` are deliberately left alone. There is no per-call escape: `EXECBRO_REDACT=off` is set by a human and needs a restart
- **Use a credential without reading it** - `list_secrets` names the handles; `http_request({auth:{secret:"api.acme.io"}})` substitutes the value host-side and issues the request from your machine — as `Authorization: Bearer` by default, or in a key header or another scheme, so a credential never has to be pasted in to cover an unsupported shape, and `vault_capture` reads a token out of the app straight into the vault when no captured request revealed one. Each credential is bound to the origin it was observed on and refused elsewhere; the vault is memory-only
- **Server- vs client-side, isolated** - `http_request` runs from the host with none of the app's TLS trust, proxy, cookie jar or mock rules; `app_request` runs inside the app with all of them. Comparing the two is how you tell a backend bug from a client one — and a 401 from the host where the app succeeds is itself the answer that the backend enforces attestation
- **App data is treated as data** - The server tells every connecting agent that logs, payloads, component trees and eval results are shaped by whatever the app talked to, and are never to be followed as instructions

### Multi-Device Debugging

- **Connect All Devices** - `scan_metro` automatically discovers and connects to all Bridgeless targets on each Metro port
- **Device Targeting** - Every tool accepts an optional `device` parameter for targeting specific devices by name (case-insensitive substring match)
- **Per-Device Buffers** - Logs and network requests are captured separately per device for clean debugging
- **Cross-Platform Comparison** - Debug iOS and Android side-by-side, comparing logs, network traffic, and component trees

### Under the Hood

- **Auto-Discovery** - Scans Metro on ports 8081, 8082, 19000-19002 automatically
- **Multi-Device Support** - Connects to all Bridgeless targets simultaneously, with per-device log and network buffers
- **Auto-Reconnection** - Exponential backoff (up to 8 attempts) when connection drops
- **Efficient Buffering** - Circular buffers: 500 logs, 200 network requests, 100 inspector selections
- **Platform Support** - Expo SDK 54+ (Bridgeless) and React Native 0.70+ (Hermes)

## Setup

Add ExecBro to Claude Code in one command — no installation, `npx` fetches the latest version on demand:

```bash
claude mcp add execbro --scope project -- npx -y execbro@latest
```

Then fully restart the client (quit and relaunch) so it picks up the new server.

Project scope writes a `.mcp.json` you can commit, so the whole team picks ExecBro up in this repo and nowhere else. Swap `project` for `user` to register it globally instead — convenient if you work in React Native all day, but it starts ExecBro in every session you open, including repos with no Metro server to connect to.

**Using a different client or need platform setup?** The [full setup guide](docs/setup.md) covers Claude Desktop, Codex CLI, Cursor, VS Code Copilot, Windsurf, Zed, and Gemini CLI, plus [Android](docs/setup.md#android) and [iOS simulator UI automation](docs/setup.md#ios-simulator--ui-automation-setup) requirements.

## Install the SDK (recommended)

ExecBro works with zero app changes, but installing the companion [`execbro-sdk`](https://www.npmjs.com/package/execbro-sdk) package is the single biggest upgrade to debugging quality. It lets you **wire up the important parts of your app — your state stores and your network layer — directly into the agent's reach**, so the AI inspects real Redux/TanStack Query state and full request/response bodies instead of guessing from the outside.

|                                          | Without SDK             | With SDK                       |
| ---------------------------------------- | ----------------------- | ------------------------------ |
| State stores (Redux, TanStack Query, …)  | Manual via `execute_in_app` | **Wired up — direct references** |
| Request/response bodies                  | Not available           | Full (including GraphQL)       |
| Startup network requests (auth, config)  | Missed                  | Captured from first fetch      |
| Console logs from startup                | May miss early logs     | Captured from first log        |
| Works on Bridgeless (Expo SDK 52+)       | Partial                 | Full                           |

It's one `npm install` plus a single `init()` call in your app's entry file. See the [SDK guide](docs/sdk.md) for install, initialization, and every config option.

## Requirements

- Node.js 20.9+
- React Native app running with Metro bundler
- **Recommended**: [`execbro-sdk`](#install-the-sdk-recommended) in your app — wires stores and the network layer into the agent for dramatically better debugging (optional; ExecBro works without it)
- **iOS UI automation**: [AXe CLI](https://github.com/cameroncooke/AXe) (`brew install cameroncooke/axe/axe`, default) or [Facebook IDB](https://fbidb.io/) (`brew install idb-companion`, opt in via `IOS_DRIVER=idb`) — required for tap, swipe, text input, accessibility on iOS Simulator
- **Optional for offline OCR fallback**: Python 3.6+ (only needed when cloud OCR is unavailable, see [OCR guide](docs/ocr.md))

## Claude Code Skills

Pre-built skills for common debugging workflows — session setup, log inspection, network debugging, and more. See the [skills guide](docs/skills.md) for the full list and installation instructions.

## Available Tools

See the [full tool reference](docs/tools.md) for all tools with descriptions. Key tools:

| Tool                                    | Description                                                                              |
| --------------------------------------- | ---------------------------------------------------------------------------------------- |
| `scan_metro`                            | **Start here** — scan for Metro servers and auto-connect                                 |
| `get_logs` / `search_logs`              | Capture and search console logs with filtering and summaries                             |
| `get_network_requests`                  | Monitor HTTP requests with method/status filtering                                       |
| `get_screen_state`                      | **Orientation snapshot** — active route, overlays, and every element with a tap-ready `(x, y)` |
| `get_screen_layout`                     | Screen map of visible components with positions, sizes, and text content                 |
| `tap`                                   | **Unified tap** — auto-detects platform, tries fiber → accessibility → OCR → coordinates |
| `pinch`                                 | **Real two-finger pinch-to-zoom** — Android emulator only (iOS in progress)              |
| `input_text`                            | Type text — targets and focuses a field itself, or `native:true` for whatever's focused. `replace:true` clears first (Fabric) |
| `dismiss_keyboard`                      | Blur the focused input and close the on-screen keyboard                                  |
| `execute_in_app`                        | Run JS expressions in the app runtime (REPL-style)                                       |
| `ios_screenshot` / `android_screenshot` | Take device screenshots — `ios_screenshot` also works on a USB-attached physical iPhone/iPad (capture only) |

## Usage

1. Start your React Native app:

    ```bash
    npm start
    # or
    expo start
    ```

2. Just describe what you want in plain language — the agent picks the right tools. You don't need to know tool names or ask for a specific one. For example:

    ```
    Connect to the simulator and investigate what caused the error on the screen
    ```
    ```
    Check the network logs and investigate why this error is happening
    ```
    ```
    Why is the current screen empty? Take a look and figure it out
    ```
    ```
    Tap the "Sign in" button and tell me what happens
    ```
    ```
    The list won't scroll — scroll it down and check what's going on
    ```
    ```
    Why does this button look wrong — what component renders it and where?
    ```

    The agent connects to Metro, reads logs and network, inspects the screen, and drives the UI as needed to answer.

## Detailed Guides

| Guide                                                      | Description                                                                     |
| ---------------------------------------------------------- | ------------------------------------------------------------------------------- |
| [Setup](docs/setup.md)                                     | Per-client MCP config (Claude, Codex, Cursor, VS Code, …), Android & iOS setup  |
| [SDK Setup](docs/sdk.md)                                   | Install & `init()` the in-app SDK to wire stores + network layer into the agent |
| [Console Logging](docs/logging.md)                         | `get_logs` parameters, filtering, summary mode, token optimization              |
| [Network Tracking](docs/network.md)                        | SDK setup for full capture, filtering, request details, statistics              |
| [Network Mocking](docs/network-mocking.md)                 | Tutorial: force a 500, drop a field, test a retry, go offline, replay a request |
| [App Inspection](docs/app-inspection.md)                   | Debug globals (Apollo, Redux, Expo Router), `execute_in_app`, limitations       |
| [Layout & Component Inspection](docs/layout-inspection.md) | `get_screen_layout`, component tree, `inspect_at_point`, `find_components`      |
| [Device Interaction](docs/device-interaction.md)           | Unified `tap`, platform-specific gestures, text input, key events               |
| [OCR Text Extraction](docs/ocr.md)                         | Cloud Vision OCR inside `tap`, offline fallback, language config                |
| [Claude Code Skills](docs/skills.md)                       | Pre-built skills for session setup, debugging, and automation                   |
| [Full Tool Reference](docs/tools.md)                       | Complete list of all 62 tools with descriptions                                 |

## How It Works

1. Fetches device list from Metro's `/json` endpoint
2. Connects to the main JS runtime via CDP (Chrome DevTools Protocol) WebSocket
3. Enables `Runtime.enable` to receive `Runtime.consoleAPICalled` events
4. Network capture via two paths:
    - **With SDK**: Reads from the SDK's in-app buffer via `Runtime.evaluate` — captures all requests from startup with full headers and bodies, including cold-start events that CDP would miss
    - **Without SDK**: Enables CDP `Network.enable` (on supported targets) or injects a JS fetch interceptor as fallback. On cold start, events emitted before the CDP connection is established are lost; subsequent reloads capture everything
5. Response mocking runs in that same injected interceptor: rules are matched before the request reaches the wire, and are re-pushed to every new JS context so they survive a reload
6. Stores logs and network requests in circular buffers for retrieval

## Connection Management

- **One server per session** — each agent session (each terminal or IDE window) runs its own ExecBro MCP server instance.
- **Connects on request, not on startup** — the server never auto-connects. It only attaches to your running React Native app when you ask it to (e.g. `scan_metro`), so it stays out of the way until you actually need a device.
- **One driver per device** — if two or more sessions in the same project point at the same Metro/device, they'll compete to control it, like a car with two steering wheels. Keep interaction to a single session per device.
- **Want parallel sessions? Give each its own device + port** — run separate work in a [git worktree](https://git-scm.com/docs/git-worktree) with its own Metro instance on a different port, and connect a second device (simulator/emulator) to it. For example, keep `main` on the default `8081` and start the worktree's Metro on `8082` (`npx react-native start --port 8082`, or `npx expo start --port 8082`), then launch that worktree's app pointed at `8082`. Each agent session then `scan_metro`s and drives its own device, so the two never fight over the connection.

## Troubleshooting

### No devices found

- Make sure the app is running on a simulator/device
- Check that Metro bundler is running (`npm start`)

### Logs not appearing

- Ensure the app is actively running (not just Metro)
- Try `clear_logs` then trigger some actions in the app
- Check `get_apps` to verify connection status
- **On cold start (first launch):** The CDP connection is established after the app's early initialization code has already run, so startup logs and network requests are missed. Once connected, use `reload_app` — the subsequent reload captures everything from the beginning because the connection is already in place. To capture startup events on every launch, install the optional [SDK](https://www.npmjs.com/package/execbro-sdk)

## Telemetry & Privacy

**No source code, file paths, or app content is ever sent.** Your app and your repo stay on your machine.

ExecBro sends two small signals:

- **Product analytics** (optional) — tool names, success/failure, and durations. This is what powers your [usage dashboard](#see-your-usage--execbrocom) and tells me which tools are flaky and worth fixing. Turn it off any time with `EXECBRO_TELEMETRY=false` in your MCP server config.
- **Usage count** — a running tally of how many tool calls you've made. It's a number, not content, and it's the one signal that keeps running when analytics is off.

See the [Telemetry & Data Collection guide](docs/telemetry.md) for the full field-by-field breakdown, and [PRIVACY.md](./PRIVACY.md) for the complete privacy policy.

## Supported React Native Versions

| Version        | Architecture          | Engine       | Status                                           |
| -------------- | --------------------- | ------------ | ------------------------------------------------ |
| Expo SDK 54+   | Bridgeless (New Arch) | Hermes       | ✓ Fully supported                                |
| RN 0.76+       | Bridgeless (New Arch) | Hermes       | ✓ Fully supported                                |
| RN 0.73 - 0.75 | Bridge (Old Arch)     | Hermes       | ✓ Fully supported (best network capture via CDP) |
| RN 0.70 - 0.72 | Bridge (Old Arch)     | Hermes / JSC | ✓ Supported                                      |
| RN < 0.70      | Bridge                | JSC          | Not tested                                       |

## Pricing

ExecBro is **free**. Every tool, no cap, no account required. [Linking an account](#see-your-usage--execbrocom) is optional and only gets you the usage dashboard.

## Feedback & Feature Requests

**Please run this at the end of your session to help me make the tools better.** ExecBro is built for AI agents, so the most valuable feedback comes from the agent itself — paste this prompt to your agent:

> Write a report about your experience with the ExecBro tools — where you were struggling and what could be improved. Save it as a Markdown file for me, then submit it using the `send_feedback` tool (type `"feedback"`) so it becomes a GitHub issue.

It takes 30 seconds: your agent runs `send_feedback`, hands you a pre-filled GitHub issue URL (environment info already attached), and you click submit — no GitHub setup, no copy-pasting. Real friction logs from real sessions are what shape the roadmap and get fixed first, so please send one. 🙏 And if you just have a quick idea or question, drop into [GitHub Discussions](https://github.com/igorzheludkov/execbro/discussions) to share feedback, request features, and vote on what gets built next.

## Package names & staying up to date

Ships as the npm package `execbro`. The package was previously published as `react-native-ai-devtools` and before that as `react-native-ai-debugger` — both legacy names keep receiving identical builds via mirror-publish, so existing installations and MCP configs keep working unchanged. New installs should use `execbro`.

> [!IMPORTANT]
> **Already using ExecBro?** `npx` caches packages indefinitely, so you may be stuck on an old version without realizing it. Update your MCP config to use `npx -y execbro@latest` (see [Setup](#setup)) so every session pulls the latest release with new tools and bug fixes. New installs after this change auto-update automatically.

## License

MIT