adb-android-control

Control an Android phone from your computer — or from another phone — over USB or Wi-Fi, with a clean Python API and CLI.

Find this project: #adb · #android · #wireless-debugging · #termux · #automation · #python · #foldable · #zfold · #fold7 · #samsung · #claude-code · #folding-phone · #phone-automation

Languages: English · Български

What it does

adb-android-control wraps the standard Android adb tool in a simple, typed Python package and CLI. Works on:

• Linux, macOS — your desktop
• Termux (Android) — run it on the phone itself, no PC needed (works great on folding phones like the Galaxy Z Fold)

Pairs with Claude Code as a skill, but works fine on its own.

Codebase at a glance

10 modules · 213 functions · 3,030 lines · every function ≤ 30 LOC · 312 tests

Contents

• Install
• Quick start
  • 1. Connect a device
  • 2. Use the CLI
  • 3. Use the Python API
  • 4. Run a workflow
• Commands
• Auto-reconnect (Termux)
• Troubleshooting
• Why this exists
• Development

Install

pip install adb-android-control        # once published to PyPI
# or from this repo:
pip install -e .

As a Claude Code skill:

git clone https://github.com/hah23255/adb-android-control.git \
    ~/.claude/skills/adb-android-control
claude /plugin marketplace add ~/.claude/skills/adb-android-control

You also need adb itself (Android platform-tools). On Termux: pkg install android-tools.

Quick start

1. Connect a device

USB:

adb devices        # tap "Allow" on the phone when it asks

Wi-Fi (Android 11+):

adb pair    <phone-ip>:<pair-port>   <pair-code>
adb connect <phone-ip>:<connect-port>

The pair code and ports come from Developer options → Wireless debugging on the phone.

The auto-reconnect service (below) finds the current Wi-Fi port automatically, so you never hardcode it.

2. Use the CLI

adb-control devices                  # what's connected
adb-control info                     # model, Android version, battery
adb-control shot                     # take a screenshot
adb-control monitor logcat -l W      # live log stream (W = warnings+)
adb-control monitor crash            # watch for crashes
adb-control radio                    # Wi-Fi + Bluetooth status
adb-control health                   # device health check (JSON)
adb-control workflow ./test.json     # run an automation script
adb-control --version

3. Use the Python API

from adb_android_control import ADBController

ctrl = ADBController()  # raises ADBNotFoundError if adb is missing
print(ctrl.devices())  # list of connected devices
info = ctrl.get_device_info()  # model, version, battery
print(f"{info.model} on Android {info.android_version}")
ctrl.screenshot("screen.png")
ctrl.tap(500, 800)  # tap at coordinates

4. Run a workflow

Workflows are JSON files that run a sequence of actions:

{
  "steps": [
    { "action": "start_app",  "params": {"package": "com.example.app"}, "delay": 3 },
    { "action": "tap_center", "delay": 1 },
    { "action": "screenshot", "params": {"path": "after_tap.png"} }
  ]
}

adb-control workflow my-test.json

22 step kinds are available (tap, swipe, type text, open apps, take screenshots, and more) — see adb_android_control/automation.py.

Commands

Auto-reconnect (Termux)

On Termux, a small service keeps your device connected in the background:

• termux/setup.sh ZFOLD7 <phone-ip> installs the service and a few shell helpers.
• Devices are stored in ~/.adb_devices as NAME=IP — no port. The port is re-discovered on every connect, so Wi-Fi port changes never break it.
• Helpers: adb-connect, adb-list, adb-add, adb-reconnect.

./termux/setup.sh ZFOLD7 192.168.0.50
adb-connect

Troubleshooting

Why this exists

Most Android automation tools are either:

• Java/Kotlin libraries — for building Android apps, not for controlling devices from a host
• UI-test frameworks (Appium, uiautomator2) — heavyweight, focused on UI tests
• Bash scripts around adb — fragile, hard to test

This project is the simple middle ground: a typed Python wrapper around everything adb can do, with clear errors, no shell=True, and no hidden state.

Development

pip install -e ".[dev]"
pytest                       # 350 tests + property-based fuzzing
pytest -m property           # property tests only
pytest -m race               # concurrency tests
pytest --cov                 # coverage report
uv build                     # build sdist + wheel into dist/

Building the package: use uv build (or pip wheel . --no-deps -w dist). python -m build does not work from the repo root — the local build/ directory shadows the build module; run it from outside the checkout if you need it.

Termux notes:

• /tmp is not writable in the Android sandbox — use ~/tmp for scratch space.
• After changing the repo, refresh the installed CLI with: uv tool install --from . adb-android-control --force

The project follows the Master Tester Doctrine — see docs/TESTING_DOCTRINE.md. In short: every public method has a test, tests never touch the real subprocess (a poison-pill adb fixture is used instead), and everything is deterministic.

Български

Какво представлява

adb-android-control обвива стандартния инструмент adb на Android в проста, типизирана Python библиотека и CLI. Работи на:

• Linux, macOS — на вашия компютър
• Termux (Android) — директно на телефона, без компютър

Съвместим е с Claude Code като умение (skill), но работи самостоятелно.

Инсталация

pip install adb-android-control        # след публикуване в PyPI
# или от това хранилище:
pip install -e .

Като Claude Code умение:

git clone https://github.com/hah23255/adb-android-control.git \
    ~/.claude/skills/adb-android-control
claude /plugin marketplace add ~/.claude/skills/adb-android-control

Трябва ви и самият adb (Android platform-tools). Под Termux: pkg install android-tools.

Бърз старт

Свързване по USB:

adb devices        # натиснете "Allow" на телефона при подкана

Безжично (Android 11+):

adb pair    <ip-на-телефона>:<pair-port>   <pair-code>
adb connect <ip-на-телефона>:<connect-port>

Кодът за двойка и портовете се намират в Опции за разработчици → Безжично отстраняване на грешки (Wireless debugging).

CLI:

adb-control devices                  # какво е свързано
adb-control info                     # модел, версия на Android, батерия
adb-control shot                     # скрийншот
adb-control monitor logcat -l W      # жив лог поток
adb-control monitor crash            # следене за сривове
adb-control radio                    # статус на Wi-Fi + Bluetooth
adb-control workflow ./test.json     # автоматизационен процес

Python API:

from adb_android_control import ADBController

ctrl = ADBController()
print(ctrl.devices())
info = ctrl.get_device_info()
ctrl.screenshot("screen.png")

Отстраняване на проблеми

Разработка

pip install -e ".[dev]"
pytest                       # 349 теста + property-based fuzzing
pytest --cov                 # отчет за покритие

Проектът следва Доктрината на главния тестер — вижте docs/TESTING_DOCTRINE.md. Накратко: всеки публичен метод има тест, тестовете никога не докосват реалния subprocess (използва се специална adb фикстура), и всичко е детерминистично.

{
  "name": "adb-android-control",
  "owner": {
    "name": "hah23255",
    "url": "https://github.com/hah23255/adb-android-control"
  },
  "metadata": {
    "description": "Comprehensive Android device control via ADB — typed Python package + CLI + Claude Code skill, doctrine-tested with 338 tests",
    "version": "2.0.1",
    "license": "MIT",
    "created": "2025-12-25",
    "updated": "2026-05-06"
  },
  "plugins": [
    {
      "name": "adb-android-control",
      "description": "Comprehensive Android device control via ADB (Android Debug Bridge). Use when user asks about: Android device management, app installation/uninstallation, APK operations, package management, file transfer (push/pull), screenshots, screen recording, input simulation (tap/swipe/text/keyevents), shell commands, logcat viewing, device info (battery/memory/storage), automation scripts, wireless ADB connection, scrcpy mirroring. Keywords: adb, android, phone, tablet, device, apk, install app, uninstall app, screenshot, screen record, tap, swipe, type text, keyevent, logcat, push file, pull file, shell, package, activity, intent, broadcast, dumpsys, getprop, settings, input, sendevent, monkey, am start, pm list, device info, battery status, wireless adb, connect device.",
      "source": "./",
      "strict": false,
      "skills": [
        "./"
      ]
    }
  ]
}