ExecBro

ExecBro

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 is recommended for the most robust log and network capture.

Get started

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

See your usage — execbro.com

Log in at 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, 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 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 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
• 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 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

Electron & Chromium (experimental)

• Desktop React apps over CDP - An Electron window or a Chrome tab connects as a chromium target alongside your simulators, and every tool takes the same device argument

• What works today - Console logs, network capture, replay and mocking (network_mock, network_condition), execute_in_app, debug globals, Redux, http_request / app_request, React component inspection (get_component_tree, find_components, inspect_component), including on Vite apps whose DevTools hook has no renderers, plus screenshot, tap, input_text, swipe (mouse-wheel scroll, and a real drag with four coordinates) and press_key (Enter, Escape, Tab, arrows, shortcuts). JavaScript dialogs (alert / confirm / prompt / beforeunload) are reported by the tool that opened them instead of timing out, page tools refuse while one is open, and handle_dialog accepts or dismisses it. Taps find elements by data-testid / id, visible text or React component name and click with real CDP mouse events. Screen reading without a screenshot: get_screen_state (tap-ready elements, what an overlay blocks), get_screen_layout, inspect_at_point and measure

• Not yet - pinch, navigate and the other mobile-only tools refuse a chromium target with a message saying so, rather than acting on the wrong device. Native HTML5 drag and drop (draggable) and hover are not handled yet

• Zero-config start - electron_launch_app({ projectPath: "path/to/app" }) starts an Electron project from its source folder with the debugging port open and connects its windows. It runs your project's own electron or electron-vite, never a packaged build

• Or opt in - Add one dev-only line to the Electron main process, then run scan_metro. Port 9222 is listed but not auto-connected, because connecting injects a network interceptor into the page. Attach with connect_metro({ port: 9222, device: "<window title>" }), or set EXECBRO_CHROMIUM_PORTS=9222 to auto-connect

  if (!app.isPackaged) app.commandLine.appendSwitch('remote-debugging-port', '9222')
  

  Keep the !app.isPackaged guard: an open debugging port on a packaged build lets anything that can reach it run code in your renderer

Native Android (preview)

• Kotlin apps without a JavaScript runtime - A native app that includes execbro-sdk-android in its debug build registers named state and commands. scan_metro finds it over adb, list_debug_globals and inspect_global read its state, run_app_command runs its commands, navigate drives Jetpack Navigation, and screenshot captures the screen
• Coming soon - The SDK is not published to Maven yet. Execbro already supports it; install instructions will follow with the SDK release

Under the Hood

• Auto-Discovery - Scans Metro on ports 8081-8090 automatically, and lists Chromium/Electron targets on 9222 (plus any ports in EXECBRO_CHROMIUM_PORTS)
• 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:

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 covers Claude Desktop, Codex CLI, Cursor, VS Code Copilot, Windsurf, Zed, and Gemini CLI, plus Android and iOS simulator UI automation requirements.

Install the SDK (recommended)

ExecBro works with zero app changes, but installing the companion 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.

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

Requirements

• Node.js 20.9+
• React Native app running with Metro bundler
• Recommended: execbro-sdk 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 (brew install cameroncooke/axe/axe, default) or Facebook IDB (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)

Claude Code Skills

Pre-built skills for common debugging workflows — session setup, log inspection, network debugging, and more. See the skills guide for the full list and installation instructions.

Available Tools

See the full tool reference for all tools with descriptions. Key tools:

Usage

1. Start your React Native app:

   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