execbro

# ExecBro

[![MCP Registry](https://img.shields.io/badge/MCP_Registry-io.github.igorzheludkov%2Fexecbro-6E56CF)](https://registry.modelcontextprotocol.io/?q=io.github.igorzheludkov%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, **required to unlock unlimited usage via ExecBro Pro**
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 your installation here is also **required to unlock [ExecBro Pro](#pricing)** — signing in and authorizing your installation is what lets the unlimited-usage plan take effect; without it, the free tier's monthly cap applies even after subscribing.

## 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
- **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 pixels from screenshots. 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. Accepts screenshot pixel coordinates, handles per-platform conversion, and returns a `verification.meaningful` signal so agents detect end-of-list, non-scrollable surfaces, and missed coordinates. Essential for scrolling virtualized lists (FlatList/SectionList) where off-screen items aren't in the fiber tree
- **UI Automation** - Swipe, long press, key events, and text input on both platforms. On Bridgeless/Fabric apps, `clear_focused_input` and `dismiss_keyboard` operate on whatever has focus, and `ios_input_text` / `android_input_text` accept `replace:true` to overwrite pre-filled values — all three update React state through `onChangeText` so controlled components (Formik, react-hook-form, useState) stay consistent
- **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)

### 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 user -- npx -y execbro@latest
```

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

**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 18+
- 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