Phonegang controls Android phones over USB by reading the accessibility tree — the same structured data that screen readers use. Instead of matching pixels or hardcoding coordinates, you find elements by their text, resource ID, or content description. It ships as a CLI, a Python library, and an MCP server that lets Claude Code tap your phone directly.

Install

git clone https://github.com/2389-research/phonegang.git
cd phonegang
uv sync

Requires Python 3.10+, an Android device with USB debugging enabled, and ADB on your PATH.

What it does

CLI commands cover the common operations: phonegang tap-text "Login", phonegang type "hello", phonegang screenshot, phonegang scroll-to "Settings". You can also dump the raw UI tree, list connected devices, manage apps, and navigate with back/home.

Python API gives you DeviceManager, ADBDevice, and DeviceController. Connect to a device, refresh the accessibility tree, find elements by text/class/resource-id/custom predicates, then tap, type, scroll, or wait for elements to appear. The tree object supports chained queries — find all buttons, filter by size, grab the clickable ones.

MCP server exposes high-level tools (get_screen, tap, type_text, wait_for) and low-level tools (tap_xy, swipe, press_key, get_ui_dump) over MCP. Add it to your Claude Code config and ask Claude to interact with your phone in natural language.

How it works

Four layers, bottom to top:

ADB layer — wraps adb-shell for raw device communication (shell commands, file push/pull, input events)
Accessibility tree parser — parses uiautomator XML dumps into queryable Python objects with bounds, text, resource IDs, and click state
Device controller — combines ADB and the parsed tree for high-level operations (find-and-tap, scroll-to-text, wait-for-element)
CLI / MCP — Click-based CLI and MCP server that expose the controller to humans and AI agents

Requirements

Python 3.10+
Android device with USB debugging enabled
ADB (Android Debug Bridge) — comes with Android SDK or install standalone
adb-shell, click, lxml (installed automatically via uv sync)