A semantic CLI wrapper around ADB designed for LLMs to interact with Android devices
A semantic CLI wrapper around ADB designed for LLMs to interact with Android devices.
Standard ADB commands require coordinate calculations, XML parsing, and arcane syntax. adbx provides semantic commands that work with element text instead of coordinates.
| Task | Raw ADB | adbx |
|---|---|---|
| Tap a button | adb shell uiautomator dump ... → parse XML → find bounds → calculate center → adb shell input tap 580 1240 | adbx tap "Submit" |
| See what's on screen | Dump XML, pull file, read manually | adbx observe |
| Type text with spaces | Escape manually: adb shell input text "hello%sworld" | adbx type "hello world" |
| Find why a tap failed | Re-dump XML, search through it | Error shows visible elements |
Smart element selection — When multiple elements match (e.g., a text label and its clickable parent), adbx automatically selects the interactive one. No manual XML inspection needed.
Actionable errors — When an element isn't found, adbx shows what is on screen:
✗ Element "Submit" not found
Visible elements:
"Sign In"
"Create Account"
Structured output — observe returns a consistent format that's easy to parse and reason about, with coordinates ready for tapping.
Text input that works — Handles spaces, special characters, and Unicode. Auto-detects ADBKeyboard for React Native apps.
adb in PATH)npm install -g adbx
# or: pnpm add -g adbx
# or: yarn global add adbx
# or: bun add -g adbx
npx adbx <command>
Add the adbx skill to Claude Code so it automatically uses adbx for Android automation:
# Install
claude plugin marketplace add joehaddad2000/adbx-cli
claude plugin install adbx
# Update (when new versions are available)
claude plugin update adbx
The primary command for understanding what's on screen:
adbx observe # Get element list
adbx observe --visual # Include screenshot
adbx observe --visual ./s.png # Screenshot at specific path
adbx observe --wait 2000 # Wait 2s before observing
Output:
=== SCREEN STATE ===
Elements: 5
"Sign In" at (540, 1200) [enabled]
"Email" at (540, 800) [enabled]
"Next month" at (819, 921) [icon, enabled]
"com.app:id/btn_submit" at (540, 1400) [id, enabled]
"Welcome" at (540, 400)
Screenshot: /path/to/screenshot.png
adbx devices # List connected devices
adbx tap "Sign In" # Tap element containing text
adbx tap 540 1200 # Tap at coordinates
adbx tap "Menu" --long # Long press
adbx tap "Item" --index 2 # Tap the 3rd match (0-indexed)
adbx tap "android:id/next" --id # Tap by resource-id
adbx type "hello@example.com" # Type into focused field
adbx clear # Clear focused field
adbx enter # Press enter key
adbx scroll down # Scroll down (vertical)
adbx scroll up # Scroll up
adbx swipe left # Swipe left (horizontal)
adbx swipe right # Swipe right
adbx back # Press back button
adbx home # Press home button
adbx wait 2000 # Wait (sleep) for 2 seconds
adbx packages # List user-installed apps
adbx packages goal # Search by name
adbx packages --all # Include system packages
adbx launch com.example.app # Launch app
adbx stop com.example.app # Force stop app
adbx clear-data com.example.app # Clear app data
--device <serial> # Target specific device (required if multiple connected)
--timeout <ms> # Override command timeout (default: 10000)
--long # Long press (tap only)
--index <n> # Select nth match when multiple elements found (tap only)
--id # Search by resource-id instead of text (tap only)
--visual, -v # Include screenshot (observe only)
--wait <ms>, -w # Wait before observing (observe only)
--all, -a # Include system packages (packages only)
# Launch app and navigate
adbx observe # Check initial state
adbx launch com.example.myapp
adbx observe --wait 2000 # Wait for app to load, then observe
adbx tap "Email"
adbx type "user@example.com"
adbx tap "Password"
adbx type "secretpassword"
adbx tap "Sign In"
adbx wait 3000 # Wait for login to complete
adbx observe --visual ./logged-in.png # Verify and capture
When you run adbx tap "Submit", the CLI:
adb shell uiautomator dumptext or content-desc matches "Submit"[100,200][300,250])adb shell input tap 200 225For text input, adbx uses standard adb shell input text which works for most native Android apps.
For React Native apps or Unicode input, install ADBKeyboard on the device. adbx automatically detects and uses it when available.
When multiple devices are connected, adbx requires explicit device selection:
adbx devices # List devices
adbx tap "Submit" --device emulator-5554
If only one device is connected, it's selected automatically.
| Command | Description |
|---|---|
devices | List connected devices and emulators |
observe [path] | Get screen state (elements + optional screenshot) |
tap <text> | Tap element by text or content-desc |
tap <x> <y> | Tap at exact coordinates |
type <text> | Type text into focused input field |
clear | Clear text in focused input field |
scroll up|down | Scroll vertically |
swipe left|right | Swipe horizontally |
wait <ms> | Wait (sleep) for specified milliseconds |
back | Press back button |
home | Press home button |
enter | Press enter/return key |
packages [query] | List/search installed packages |
launch <package> | Launch app by package name |
stop <package> | Force stop app |
clear-data <package> | Clear app data (cache, settings, databases) |
adbx provides clear error messages with context:
$ adbx tap "Nonexistent"
✗ Element "Nonexistent" not found
Visible elements:
"Sign In"
"Create Account"
"Forgot Password"
$ adbx scroll left
✗ scroll requires direction: up or down
MIT
FAQs
A semantic CLI wrapper around ADB designed for LLMs to interact with Android devices
The npm package adbx receives a total of 0 weekly downloads. As such, adbx popularity was classified as not popular.
We found that adbx demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Multiple high-impact npm maintainers confirm they have been targeted in the same social engineering campaign that compromised Axios.
Security News
Axios compromise traced to social engineering, showing how attacks on maintainers can bypass controls and expose the broader software supply chain.
Security News
Node.js has paused its bug bounty program after funding ended, removing payouts for vulnerability reports but keeping its security process unchanged.