agent-android

LLM-friendly CLI for Android automation via ADB and UIAutomator2. Designed for AI agents to interact with Android devices through structured JSON commands and responses.

Prerequisites

• Node.js 18+
• Android SDK with ADB in PATH
• Android device/emulator with USB debugging enabled
• UIAutomator2 server APK (see Setup)

Installation

npm install -g agent-android

Setup

Download the UIAutomator2 server APK:

mkdir -p ~/.agent-android
# Download from: https://github.com/appium/appium-uiautomator2-server/releases
# Save as: ~/.agent-android/uia2-server.apk

Usage

# List connected devices
agent-android list-devices

# Start automation session
agent-android start-session --device emulator-5554

# Get UI accessibility tree (JSON with element refs)
agent-android snapshot

# Interact with elements using refs from snapshot
agent-android tap @e5
agent-android type @e10 "hello world"
agent-android clear @e10
agent-android swipe @e3 up

# Wait for element to appear
agent-android wait @e5 --timeout 5000

# App management
agent-android install ./app.apk
agent-android launch com.example.app
agent-android terminate com.example.app

# Navigation
agent-android back
agent-android home

# Capture screenshot
agent-android screenshot --out screen.png

# Check status
agent-android status

# Stop session
agent-android stop-session

Commands

| Command | Description | |---------|-------------| | list-devices | List connected Android devices | | start-session --device <id> | Start automation session | | stop-session | Stop automation session | | status | Check daemon and device status | | snapshot | Get accessibility tree as JSON | | screenshot [--out file] | Capture screenshot | | tap <ref> | Tap element by ref | | type <ref> <text> | Type text into element | | clear <ref> | Clear text field | | swipe <ref> <dir> | Swipe (up/down/left/right) | | wait <ref> [--timeout ms] | Wait for element | | install <apk> | Install APK | | launch <package> | Launch app | | terminate <package> | Force stop app | | back | Press back button | | home | Press home button |

Options

• --session <name> - Use named session (default: "default")
• --help, -h - Show help

Output Format

All commands return JSON:

{
  "success": true,
  "data": { ... }
}

Or on error:

{
  "success": false,
  "error": "Error message"
}

Architecture

• CLI (agent-android) - Command interface
• Daemon - Background process managing device sessions
• UIAutomator2 - Android instrumentation for UI automation

License

MIT