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

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

Yarn

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

Bun

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.

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 or emulator.
• Operate the app — resolve, install, launch, restart, deep-link, and inspect the project app.
• Verify the UI — find semantic elements, act by intent, assert state, and capture the screen.
• Debug with evidence — keep focused logs, 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.

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

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, logs, screenshots, and saved evidence. Every result is schema-validated 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 run against the same selected target through ANDROID_SERIAL. 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

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

Each executed run retains a redacted evidence bundle with its result, timeline, problems, focused logcat, AI context, JUnit XML, and GitHub step summary. 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 →

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.
• 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

| Projects | Package managers | CLI runtimes | Hosts | | --- | --- | --- | --- | | Expo · React Native · Flutter · Capacitor · Gradle · custom | npm · pnpm · Yarn · Bun | Node.js · Bun · Deno | macOS · Linux · Windows |

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.
• Stale UI references are rejected before input is sent.
• Machine data stays on stdout; human diagnostics stay on stderr.

Review the complete threat model →

Documentation

| Guide | Start here when you want to… | | --- | --- | | Getting started | Reach the first ready development session. | | Development sessions | Configure frameworks, commands, ports, readiness, and cleanup. | | Targets and Wireless debugging | Pair, connect, recover, or explicitly select a target. | | Apps and evidence | Control the app and capture screenshots or recordings. | | Safe UI automation | Find, act on, and verify the current Android UI. | | Logs and AI context | Diagnose a failure with bounded, redacted evidence. | | AI agent integration | Connect an MCP-capable coding agent. | | Automation | Use readiness, exit codes, JSON, NDJSON, JUnit, and CI artifacts. | | Configuration | Share project presets, hooks, aliases, and policies. | | Troubleshooting | Resolve a known setup, target, UI, or session problem. | | Compatibility | Check hosts, runtimes, package managers, and support tiers. | | Example configs | Copy a framework or custom-project configuration. |

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

Project

Changelog · Contributing · Security · MIT License

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