{
  "markdown": "# ExecBro\n\n[![MCP Registry](https://img.shields.io/badge/MCP_Registry-com.execbro%2Fexecbro-6E56CF)](https://registry.modelcontextprotocol.io/?q=com.execbro%2Fexecbro)\n\n**Give your AI assistant eyes and hands into your running React Native app.** Like Chrome DevTools — but for AI agents.\n\nBuild, debug, and verify features end-to-end — without leaving the chat.\n\nExecBro 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.\n\n<p align=\"center\">\n  <img src=\"https://raw.githubusercontent.com/igorzheludkov/execbro/main/docs/demo/get_logs_demo.gif\" alt=\"ExecBro demo\" width=\"800\" />\n</p>\n\n## Get started\n\n1. [Setup ExecBro as an MCP server for your agent of choice](#setup)\n2. [Setup UI automation helpers](docs/setup.md#ios-simulator--ui-automation-setup)\n3. [Install the SDK in your React Native app](#install-the-sdk-recommended) — optional, but recommended for the most robust log, network, and state experience\n4. [Authorize and link to the web dashboard](#see-your-usage--execbrocom) — optional, for usage stats and session history\n5. Start your React Native app (`npm start` / `expo start`)\n6. [Ask your AI assistant](#usage) in plain language — e.g. \"Connect to the simulator and investigate what caused the error on the screen\"\n\n## See your usage — [execbro.com](https://execbro.com)\n\nLog 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.\n\nLinking is also how [ExecBro Pro](#pricing) attaches to your installation, if you ever subscribe.\n\n## Features\n\n### Runtime Interaction\n\n- **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\n- **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\n- **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)\n- **JavaScript Execution** - Run code directly in your app (REPL-style) and inspect results\n- **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\n- **Bundle Error Detection** - Get Metro bundler errors and compilation issues with file locations\n- **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\n\n### Device Control\n\n- **iOS Simulator** - Screenshots, app management, URL handling, boot/terminate (via simctl)\n- **Android Devices** - Screenshots, app install/launch, package management (via ADB)\n- **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\n- **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\n- **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\n- **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\n- **Accessibility Inspection** - Query UI hierarchy to find elements by text, label, or resource ID\n- **OCR Text Extraction** - Extract visible text with tap-ready coordinates via Google Cloud Vision (works on any screen content)\n\n### Credential Safety\n\n- **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\n- **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\n- **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\n- **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\n\n### Multi-Device Debugging\n\n- **Connect All Devices** - `scan_metro` automatically discovers and connects to all Bridgeless targets on each Metro port\n- **Device Targeting** - Every tool accepts an optional `device` parameter for targeting specific devices by name (case-insensitive substring match)\n- **Per-Device Buffers** - Logs and network requests are captured separately per device for clean debugging\n- **Cross-Platform Comparison** - Debug iOS and Android side-by-side, comparing logs, network traffic, and component trees\n\n### Under the Hood\n\n- **Auto-Discovery** - Scans Metro on ports 8081, 8082, 19000-19002 automatically\n- **Multi-Device Support** - Connects to all Bridgeless targets simultaneously, with per-device log and network buffers\n- **Auto-Reconnection** - Exponential backoff (up to 8 attempts) when connection drops\n- **Efficient Buffering** - Circular buffers: 500 logs, 200 network requests, 100 inspector selections\n- **Platform Support** - Expo SDK 54+ (Bridgeless) and React Native 0.70+ (Hermes)\n\n## Setup\n\nAdd ExecBro to Claude Code in one command — no installation, `npx` fetches the latest version on demand:\n\n```bash\nclaude mcp add execbro --scope project -- npx -y execbro@latest\n```\n\nThen fully restart the client (quit and relaunch) so it picks up the new server.\n\nProject 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.\n\n**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.\n\n## Install the SDK (recommended)\n\nExecBro 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.\n\n|                                          | Without SDK             | With SDK                       |\n| ---------------------------------------- | ----------------------- | ------------------------------ |\n| State stores (Redux, TanStack Query, …)  | Manual via `execute_in_app` | **Wired up — direct references** |\n| Request/response bodies                  | Not available           | Full (including GraphQL)       |\n| Startup network requests (auth, config)  | Missed                  | Captured from first fetch      |\n| Console logs from startup                | May miss early logs     | Captured from first log        |\n| Works on Bridgeless (Expo SDK 52+)       | Partial                 | Full                           |\n\nIt'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.\n\n## Requirements\n\n- Node.js 20.9+\n- React Native app running with Metro bundler\n- **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)\n- **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\n- **Optional for offline OCR fallback**: Python 3.6+ (only needed when cloud OCR is unavailable, see [OCR guide](docs/ocr.md))\n\n## Claude Code Skills\n\nPre-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.\n\n## Available Tools\n\nSee the [full tool reference](docs/tools.md) for all tools with descriptions. Key tools:\n\n| Tool                                    | Description                                                                              |\n| --------------------------------------- | ---------------------------------------------------------------------------------------- |\n| `scan_metro`                            | **Start here** — scan for Metro servers and auto-connect                                 |\n| `get_logs` / `search_logs`              | Capture and search console logs with filtering and summaries                             |\n| `get_network_requests`                  | Monitor HTTP requests with method/status filtering                                       |\n| `get_screen_state`                      | **Orientation snapshot** — active route, overlays, and every element with a tap-ready `(x, y)` |\n| `get_screen_layout`                     | Screen map of visible components with positions, sizes, and text content                 |\n| `tap`                                   | **Unified tap** — auto-detects platform, tries fiber → accessibility → OCR → coordinates |\n| `pinch`                                 | **Real two-finger pinch-to-zoom** — Android emulator only (iOS in progress)              |\n| `input_text`                            | Type text — targets and focuses a field itself, or `native:true` for whatever's focused. `replace:true` clears first (Fabric) |\n| `dismiss_keyboard`                      | Blur the focused input and close the on-screen keyboard                                  |\n| `execute_in_app`                        | Run JS expressions in the app runtime (REPL-style)                                       |\n| `ios_screenshot` / `android_screenshot` | Take device screenshots                                                                  |\n\n## Usage\n\n1. Start your React Native app:\n\n    ```bash\n    npm start\n    # or\n    expo start\n    ```\n\n2. 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:\n\n    ```\n    Connect to the simulator and investigate what caused the error on the screen\n    ```\n    ```\n    Check the network logs and investigate why this error is happening\n    ```\n    ```\n    Why is the current screen empty? Take a look and figure it out\n    ```\n    ```\n    Tap the \"Sign in\" button and tell me what happens\n    ```\n    ```\n    The list won't scroll — scroll it down and check what's going on\n    ```\n    ```\n    Why does this button look wrong — what component renders it and where?\n    ```\n\n    The agent connects to Metro, reads logs and network, inspects the screen, and drives the UI as needed to answer.\n\n## Detailed Guides\n\n| Guide                                                      | Description                                                                     |\n| ---------------------------------------------------------- | ------------------------------------------------------------------------------- |\n| [Setup](docs/setup.md)                                     | Per-client MCP config (Claude, Codex, Cursor, VS Code, …), Android & iOS setup  |\n| [SDK Setup](docs/sdk.md)                                   | Install & `init()` the in-app SDK to wire stores + network layer into the agent |\n| [Console Logging](docs/logging.md)                         | `get_logs` parameters, filtering, summary mode, token optimization              |\n| [Network Tracking](docs/network.md)                        | SDK setup for full capture, filtering, request details, statistics              |\n| [Network Mocking](docs/network-mocking.md)                 | Tutorial: force a 500, drop a field, test a retry, go offline, replay a request |\n| [App Inspection](docs/app-inspection.md)                   | Debug globals (Apollo, Redux, Expo Router), `execute_in_app`, limitations       |\n| [Layout & Component Inspection](docs/layout-inspection.md) | `get_screen_layout`, component tree, `inspect_at_point`, `find_components`      |\n| [Device Interaction](docs/device-interaction.md)           | Unified `tap`, platform-specific gestures, text input, key events               |\n| [OCR Text Extraction](docs/ocr.md)                         | Cloud Vision OCR inside `tap`, offline fallback, language config                |\n| [Claude Code Skills](docs/skills.md)                       | Pre-built skills for session setup, debugging, and automation                   |\n| [Full Tool Reference](docs/tools.md)                       | Complete list of all 62 tools with descriptions                                 |\n\n## How It Works\n\n1. Fetches device list from Metro's `/json` endpoint\n2. Connects to the main JS runtime via CDP (Chrome DevTools Protocol) WebSocket\n3. Enables `Runtime.enable` to receive `Runtime.consoleAPICalled` events\n4. Network capture via two paths:\n    - **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\n    - **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\n5. 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\n6. Stores logs and network requests in circular buffers for retrieval\n\n## Connection Management\n\n- **One server per session** — each agent session (each terminal or IDE window) runs its own ExecBro MCP server instance.\n- **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.\n- **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.\n- **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.\n\n## Troubleshooting\n\n### No devices found\n\n- Make sure the app is running on a simulator/device\n- Check that Metro bundler is running (`npm start`)\n\n### Logs not appearing\n\n- Ensure the app is actively running (not just Metro)\n- Try `clear_logs` then trigger some actions in the app\n- Check `get_apps` to verify connection status\n- **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)\n\n## Telemetry & Privacy\n\n**No source code, file paths, or app content is ever sent.** Your app and your repo stay on your machine.\n\nExecBro sends two small signals:\n\n- **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.\n- **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.\n\nSee 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.\n\n## Supported React Native Versions\n\n| Version        | Architecture          | Engine       | Status                                           |\n| -------------- | --------------------- | ------------ | ------------------------------------------------ |\n| Expo SDK 54+   | Bridgeless (New Arch) | Hermes       | ✓ Fully supported                                |\n| RN 0.76+       | Bridgeless (New Arch) | Hermes       | ✓ Fully supported                                |\n| RN 0.73 - 0.75 | Bridge (Old Arch)     | Hermes       | ✓ Fully supported (best network capture via CDP) |\n| RN 0.70 - 0.72 | Bridge (Old Arch)     | Hermes / JSC | ✓ Supported                                      |\n| RN < 0.70      | Bridge                | JSC          | Not tested                                       |\n\n## Pricing\n\nExecBro 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).\n\n> [!NOTE]\n> **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).\n\n## Feedback & Feature Requests\n\n**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:\n\n> 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.\n\nIt 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.\n\n## Package names & staying up to date\n\nShips 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`.\n\n> [!IMPORTANT]\n> **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.\n\n## License\n\nMIT\n",
  "bytes": 24281,
  "sha": "0e0188f841df389317c0a88967163425a0a8d715aaca2ebe387351a0f81c9cd2",
  "repo_slug": "igorzheludkov/execbro",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_com_execbro_execbro_dadb0b9d/readme"
}