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    :   
adb connect :<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