ExecBro
Gives AI agents eyes and hands into running React Native apps: logs, REPL, tap, screenshots
Open source Open in the app JSON README (API)
About
Gives AI agents eyes and hands into running React Native apps: logs, REPL, tap, screenshots
Details
- Kind
- MCP servers
- Topic
- Web search, scraping & browser
- Publisher
- com.execbro
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 2.11.0
- Stars
- 72
- Forks
- 9
- Last push
- 2026-09-07T21:38:11Z
- Repository state
- ativo
- Language
- TypeScript
- License
- NOASSERTION
- Added
- 2026-08-29 03:01:07
- Updated
- 2026-09-07 23:04:22
- Origin id
com.execbro/execbro
README
# ExecBro
[](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 also how [ExecBro Pro](#pricing) attaches to your installation, if you ever subscribe.
## 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 |
## 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, so the free tier knows where you stand against its monthly allowance. 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, full power, no feature gates, no account needed to start. The free tier covers **600 tool calls a month**, which is evaluation plus everyday debugging; most people never reach it. If you drive your agent hard all day, **ExecBro Pro** ($8.99/mo) lifts the cap and includes every hosted feature as it ships. See [execbro.com/pricing](https://execbro.com/pricing).
> [!NOTE]
> **Grandfather notice:** the 600-call monthly cap starts applying **2026-08-01** for new installs. If you already had ExecBro installed before then, you get a free month on top — your cap doesn't start until **2026-08-31**. You'll also see this as an in-app notice. No action needed unless you want to [link your account and upgrade to Pro](#see-your-usage--execbrocom) ahead of time. Questions? [zigor535@gmail.com](mailto:zigor535@gmail.com).
## 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