Android Autonomous Debugger

Trigger: When the user asks to debug, test, or verify an Android app on a physical device, or when a build-and-test cycle is needed against a connected Android device.

Keywords: android debug, test on device, install apk, check crash, mobile testing, e2e test, verify on phone, run on device, screen capture device.

CRITICAL: Use adb-run.sh for All Commands

NEVER use source scripts/lib/adb-wrapper.sh && cmd1 && cmd2 — Claude Code's shell-aware permission system blocks compound &&/|| chains, causing permission popups that break autonomous operation.

ALWAYS use ./scripts/adb-run.sh which wraps everything in a single command:

# WRONG — causes permission popups:
source scripts/lib/adb-wrapper.sh && adb_auto_select && adb_screenshot /tmp/s.png

# CORRECT — single command, no popups:
./scripts/adb-run.sh adb_auto_select "adb_screenshot /tmp/s.png"

Each argument is one function call. Quote arguments with spaces:

./scripts/adb-run.sh adb_auto_select "adb_tap 500 900" "adb_screenshot /tmp/after.png"
./scripts/adb-run.sh adb_auto_select "adb_install ./app.apk" "adb_launch com.savia.mobile"
./scripts/adb-run.sh adb_auto_select "adb_logcat_errors 30 com.savia.mobile"

Prerequisites

• Android device connected via USB with USB debugging enabled
• ADB available (auto-detected from Android SDK)
• APK built and ready (or source available to build)

Core Capabilities

1. Device Discovery

./scripts/adb-run.sh adb_auto_select adb_device_info
./scripts/adb-run.sh adb_devices

2. APK Lifecycle

./scripts/adb-run.sh adb_auto_select "adb_install ./path/to/app.apk"
./scripts/adb-run.sh adb_auto_select "adb_uninstall com.package.name"
./scripts/adb-run.sh adb_auto_select "adb_launch com.package.name"
./scripts/adb-run.sh adb_auto_select "adb_stop com.package.name"
./scripts/adb-run.sh adb_auto_select "adb_clear_data com.package.name"

3. Visual Inspection

./scripts/adb-run.sh adb_auto_select "adb_screenshot /tmp/screen.png"
./scripts/adb-run.sh adb_auto_select "adb_hierarchy /tmp/ui.xml"
./scripts/adb-run.sh adb_auto_select "adb_snapshot /tmp/prefix"

4. UI Interaction

./scripts/adb-run.sh adb_auto_select "adb_tap 500 900"
./scripts/adb-run.sh adb_auto_select "adb_tap_id login_button"
./scripts/adb-run.sh adb_auto_select "adb_tap_text Conectar"
./scripts/adb-run.sh adb_auto_select "adb_swipe 500 1200 500 400 300"
./scripts/adb-run.sh adb_auto_select adb_scroll_down
./scripts/adb-run.sh adb_auto_select "adb_type hello_world"
./scripts/adb-run.sh adb_auto_select "adb_key back"

5. Debugging

./scripts/adb-run.sh adb_auto_select adb_logcat_clear
./scripts/adb-run.sh adb_auto_select "adb_logcat_errors 30"
./scripts/adb-run.sh adb_auto_select "adb_logcat_errors 60 com.savia.mobile"
./scripts/adb-run.sh adb_auto_select "adb_detect_crash 60"
./scripts/adb-run.sh adb_auto_select "adb_meminfo com.savia.mobile"

6. Element Finding & Waiting

./scripts/adb-run.sh adb_auto_select "adb_find_by_id btn_send"
./scripts/adb-run.sh adb_auto_select "adb_find_by_text Savia"
./scripts/adb-run.sh adb_auto_select "adb_wait_for_text Welcome 15"
./scripts/adb-run.sh adb_auto_select "adb_wait_for_id main_screen 10"

Autonomous Debug Cycle

When asked to verify an app on device, follow this cycle:

Phase 1: Setup

./scripts/adb-run.sh adb_auto_select adb_device_info adb_logcat_clear

Phase 2: Install & Launch

./scripts/adb-run.sh adb_auto_select "adb_install <path>" "adb_launch <package>" "adb_wait_for_text MainScreen 15" "adb_screenshot /tmp/baseline.png"

Phase 3: Interact & Verify

For each screen/feature to test:

./scripts/adb-run.sh adb_auto_select "adb_tap_text FeatureName" "adb_wait_for_text ExpectedText 10" "adb_screenshot /tmp/feature-X.png" "adb_logcat_errors 10"

If a crash is detected:

./scripts/adb-run.sh adb_auto_select "adb_detect_crash 30" "adb_logcat_errors 60 com.package"

Phase 4: Report

Summarize: PASS/FAIL per screen tested. Include screenshots as evidence. Include crash logs if any. Suggest fixes based on stack traces.

Security Model

Operations are classified into three security levels:

Level	Examples	Behavior
Safe	screenshot, logcat, hierarchy, tap, type	Auto-approved
Risky	install, uninstall, force-stop, clear data	Logged, allowed
Blocked	rm -rf, format, su, dd	Always rejected
The android-adb-validate.sh hook enforces this classification.

Environment Variables

Variable	Default	Description
ADB_PATH	auto-detect	Path to ADB binary
ADB_DEVICE	auto-select	Target device serial
ADB_RETRIES	3	Max retries per command
ADB_TIMEOUT	30	Command timeout (seconds)

Tips for Agents

• ALWAYS use ./scripts/adb-run.sh — never source wrapper.sh && ...
• Always start with adb_auto_select; chain many functions in one call
• Screenshots BEFORE and AFTER each interaction; use adb_wait_for_text instead of sleep