ADB Ready

The local Android runtime for coding agents.

Prepare one Android target, run your project, operate the app, and return verified evidence—for developers, agents, and CI.

Quick start · What it does · AI agents · CI · Documentation

Quick start

Install ADB Ready in the Android project your team wants to run:

npm · default

npm install --save-dev adb-ready
npx adb-ready dev

pnpm add --save-dev adb-ready
pnpm exec adb-ready dev

yarn add --dev adb-ready
yarn adb-ready dev

bun add --dev adb-ready
bunx adb-ready dev

ADB Ready handles the state around ADB that a person, script, or coding agent should not guess: which device belongs to the run, whether the app is ready, which ports and processes the session owns, and what evidence survives a failure. It orchestrates your real ADB and framework tools; it does not replace them or require an ADB Ready account, hosted service, or model API key.

Running adb-ready without a command opens the interactive workflow home. adbr is the shorter alias for the same CLI. New to Android device setup? Open Start → Set up first device for a guided USB, Wireless debugging, or emulator path. The home and its focused menus adapt to the detected terminal width and height, including narrow split panes and short terminals, without relying on scrolling to reveal an action.

What ADB Ready does

• Run the project — select one target, prepare ports, launch the framework, and keep the session healthy.
• Connect the device — discover, pair, reconnect, and deterministically bind a physical device, emulator, or protected remote ADB server without silently restarting shared infrastructure.
• Operate the app — resolve, install, launch, restart, deep-link, and inspect the project app.
• Verify the UI — find semantic elements, act by intent—including international text, protected input, keyboard state, and runtime-permission dialogs—assert state, audit accessibility, and capture the screen.
• Debug with evidence — keep focused logs, correlated crash/ANR/native findings, session history, screenshots, recordings, and redacted context together.
• Automate a real device — gate a finite command on readiness and return stable results, reports, and artifacts.
• Run cloud device matrices — validate live Firebase dimensions, run instrumentation or Robo tests, and retain normalized provider evidence without storing cloud credentials.
• Fan out across explicit targets — run the same bounded check on named local, AVD, remote-ADB, or Firebase pools while each target keeps an isolated lease, session, result, and cleanup boundary.

Choose how you work

With a coding agent

Connect the current project to Codex, Claude Code, Cursor, VS Code/Copilot, Windsurf, or another MCP client:

npx adb-ready agent setup codex

Setup writes the project MCP bridge and a version-matched Agent Skill. Use --mcp-profile debug, session, or ui to expose only the tools needed for that job; full remains the default.

Then ask for the outcome you want:

Start this Expo app on my Android phone, wait until the login screen is actually ready, verify my change, and keep the failure evidence.

The local MCP server gives agents typed tools for target readiness, durable development sessions, app lifecycle, semantic UI, correlated failure evidence, screenshots, and saved diagnostics. Every result is schema-validated, annotated for safety, and checked against fresh device state. Agents do not receive a generic shell, unrestricted raw ADB, or app removal.

Connect an AI agent in minutes →

From your terminal

Check the host, inspect visible targets, and start the complete development loop:

npx adb-ready doctor
npx adb-ready devices
npx adb-ready dev

Expo, React Native, Flutter, Capacitor, Gradle, and custom commands all receive the same selected target through ANDROID_SERIAL. Expo sessions go further: ADB Ready starts Metro without Expo's all-device auto-open path, resolves the project deep link from the verified server, and opens it only on the selected ADB transport. Add local services with repeated --port flags or replace the detected command after --:

adb-ready dev --port 8081 --port 8000
adb-ready dev -- pnpm run android:local
adb-ready dev --dry-run --json

For Expo projects, explicit localhost URLs in EXPO_PUBLIC_* environment variables are discovered with Expo's own development environment resolution. ADB Ready safely adds their ports to the selected target and verifies the host services before calling the session ready. Explicit port configuration always wins, and --no-auto-reverse-localhost disables discovery when required. IPv4 and IPv6 loopback listeners are supported; when ADB cannot reach an IPv6-only service directly, ADB Ready creates and cleans a local session bridge.

In an interactive Expo session that ADB Ready owns, the ready state activates verified r reload, m developer-menu, ? help, and Ctrl+C cleanup controls. ADB Ready advertises only actions it can execute; attached Metro servers keep their controls in the original terminal, while automation and redirected output stay prompt-free. See live-session behavior →

If Expo or React Native Metro is already running, ADB Ready verifies its standard status endpoint and project identity before attaching the Android session without restarting or owning that server. A Metro server from another project—or an unrelated process on the same port—is reported as a clear conflict instead of being reused.

Reach your first ready session →

In CI and automation

Wait for declared readiness, execute one bounded verification command, preserve its exit code, and clean only resources created by the run:

npx adb-ready run -- npm run test:e2e

Or make the target and deployment part of the same bounded job:

npx adb-ready run --avd Pixel_9_API_36 --deploy --variant debug -- \
  maestro test .maestro/smoke.yaml

Each executed run retains a redacted evidence bundle with its result, timeline, problems, focused logcat, native verifier output and artifacts, AI context, JUnit XML, and GitHub step summary. Maestro and Android CLI primitives are pinned to the leased target automatically. Existing matching emulators are reused; only an emulator started by that run is stopped. Scripts also get deterministic JSON and NDJSON contracts:

adb-ready devices --json --non-interactive
adb-ready logs --package com.example.app --format ndjson
adb-ready sessions list --status failed --since 24h --limit 5

Build a readiness-gated device job →

Need a hosted target first? Start from the maintained GitHub Actions emulator workflow, which runs one bounded target-locked job and preserves evidence even when verification fails. For a dedicated real device, use the manual-only self-hosted physical-device recipe.

One target. One verified loop.

find or recover one Android target
        ↓
bind the complete run to that target
        ↓
prepare only the ports the project needs
        ↓
start the framework and wait for declared readiness
        ↓
watch target · ports · logs · child process
        ↓
recover safely or return bounded failure evidence

• Existing matching port mappings are reused; conflicts are not overwritten.
• Routine successful health polls stay silent; only failures, recovery actions, and meaningful session state changes become durable output.
• ready means the selected target, required services, configured checks, and framework launch have all succeeded while the owned development process is not already failing; a passed port check alone never produces a ready session.
• Wireless and port recovery is bounded and independently verified.
• An ADB server restart is never hidden inside recovery.
• On exit, ADB Ready cleans only resources owned by that session.
• The final exit code and a project-scoped session record are preserved.

Keep your existing stack

The standard npm entrypoint requires Android SDK Platform-Tools and Node.js 22 or newer. The published package is architecture-neutral JavaScript with no native addon or artificial OS/CPU block. A working ADB executable remains the Android transport backend.

See tested and upstream-capable support tiers →

Trust by default

• One selected target is used consistently for every operation in a session.
• Target leases prevent concurrent ADB Ready processes from mutating the same target without an explicit takeover.
• Destructive or device-wide actions require an explicit command or confirmation.
• Pairing codes never enter command-line arguments.
• Session data is bounded, redacted, private to the local user, and never uploaded by ADB Ready.
• Crash diagnostics are promoted only after ADB Ready verifies the application package on the selected target; unrelated device-process failures remain explicitly unattributed evidence.
• Stale UI references are rejected before input is sent.
• UI hierarchy capture is serialized per target across CLI and MCP processes, while independent targets remain parallel.
• Field replacement verifies values without confusing a declared Android hint for user-entered text.
• Screen recordings require a readable MP4 and a real multi-frame timeline; a filename and hash alone never count as verified video evidence.
• Machine data stays on stdout; human diagnostics stay on stderr.

Review the complete threat model →

Documentation

Run adb-ready --help for the complete command list or adb-ready help COMMAND for focused options.

Sponsors

ADB Ready is independently developed and maintained. Sponsorship helps fund compatibility testing, real-device validation, CI, documentation, and reliable releases.

Sponsor ADB Ready and my open-source work →

Project

Changelog · Contributing · Security · MIT License

ADB Ready is Android-only. It exposes target-bound workflows rather than a generic remote shell.