Skip to main content

🤖 droid-agent

Give any AI agent hands on a real Android device — zero install on the phone.

dump a screen → get numbered interactive elements → tap 3. That's it.

CI PyPI Python License: MIT

demo

Why

Every other Android-agent tool makes you install something on the phone first — an Appium server, a companion APK, an accessibility service. droid-agent needs nothing on the device. Just adb, which you already have:

  • 🔢 browser-use for Android — dump distills the uiautomator tree into a short numbered list of actionable refs, not a 500-line XML blob
  • 📦 zero dependencies — pure stdlib, installs in <1s, works offline
  • 🤖 agent-first — every command has --json; ships a built-in MCP server
  • 📱 anything with adb — real phones, emulators, Android TVs, Android Auto, WSA, even Android-x86 VMs

Install

pipx install droid-agent          # recommended
# or: pip install droid-agent

pipx install 'droid-agent[mcp]'   # + MCP server for Claude Code / Cursor / Devin

Prerequisite: platform-tools (adb) on your PATH, and a device with USB or wireless debugging enabled.

60-second tour

droid-agent devices                 # what's attached
droid-agent connect 192.168.1.42    # wireless adb (or just plug USB)
droid-agent dump                    # see the screen the way an agent does

Real output, straight off a POCO F5:

[ 1] ()    Search settings                                  ( 540, 497)
[ 2] |||   recyclerview                                     ( 540,1487)
[ 3] ()    About phone                                      ( 540, 663)
[ 4] ()    System apps updater                              ( 540, 817)
[ 5] ()    Security status                                  ( 540, 971)
[ 6] ()    Wi-Fi                                            ( 540,1159)
[ 7] ()    Bluetooth                                        ( 540,1313)
[ 8] ()    Mobile networks                                  ( 540,1467)
[ 9] ()    Interconnectivity                                ( 540,1621)

15 elements · tap with `droid-agent tap <ref>`
droid-agent tap 3                   # taps "About phone"
droid-agent type "me@x.com"         # types into the focused field
droid-agent swipe up                # scroll the list
droid-agent key back                # keyevents by name
droid-agent open com.whatsapp       # launch any app
droid-agent screenshot shot.png     # PNG capture
droid-agent state                   # foreground app, screen on/off, size

For agents, everything is one flag away from JSON: droid-agent --json dump.

Use it with your agent (MCP)

{
  "mcpServers": {
    "droid-agent": { "command": "droid-agent", "args": ["mcp"] }
  }
}

Tools exposed: devices, dump_ui, tap, tap_xy, type_text, swipe, key, open_app, close_app, device_state, screenshot, wait.

Commands

Command What it does
devices list attached devices + state
connect / pair / disconnect wireless adb (Android 11+ pairing supported)
dump numbered interactive elements → ~/.droid-agent/session.json
tap <ref|x,y> / long-press touch by ref from last dump, or raw coords
type <text> input text (spaces handled) into focused field
swipe up|down|left|right or x1 y1 x2 y2 scroll / gestures
key back|home|enter|tab|del|power… keyevents by name
open / close / install / uninstall app lifecycle
screenshot / state PNG capture · foreground app + screen info
shell <cmd> raw adb escape hatch
mcp stdio MCP server

How it compares

droid-agent droidrun/mobilerun mobile-mcp Appium
On-device install none Portal APK + accessibility svc Appium driver Appium server + settings app
Time to first tap seconds minutes minutes ~30 min
What it is primitive layer full agent framework MCP bridge test framework
Deps 0 (stdlib) LLM SDKs, uv, portal node, appium java/node stack
LLM coupling none — BYO agent built-in providers none none

Different tool for a different job: they're agent frameworks; this is the curl of Android control — a primitive layer any agent (or human) can call.

Agent workflow pattern

dump → read refs → tap/type → wait → dump → verify → repeat

The dump warns when refs are >120s old (the UI may have moved). tap on a missing ref tells you to re-dump instead of tapping blind.

FAQ

Does it need root? No — just USB/wireless debugging enabled.

iOS? No. Use iphone-cli — this one is Android-only by design.

Passwords? Elements flagged password="true" are masked in dumps and never persisted to the session file.

CI? Point it at an emulator (emulator-5554) — same interface, --json for parsing.

Contributing

See CONTRIBUTING.md. Bug reports and false-positive element-detection reports especially welcome — attach droid-agent dump --json plus a screenshot.

License

MIT — see LICENSE.


If this saved you a setup afternoon — drop a ⭐

Metadata

Release files for droid-agent 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for droid-agent 0.1.0
File Size Uploaded Provenance Actions
droid_agent-0.1.0.tar.gz 1.5 MB Without provenance Details for droid_agent-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for droid-agent 0.1.0
File Interpreter ABI Platform Actions
droid_agent-0.1.0-py3-none-any.whl Python 3 none any Details for droid_agent-0.1.0-py3-none-any.whl

Total release size: 1.5 MB

Release files / droid_agent-0.1.0.tar.gz

Download URL droid_agent-0.1.0.tar.gz
Size 1.5 MB
Tags Source
SHA-256 checksum
How to use checksums
feafbf3b9c48a9434fe2ca1f40a56a9833e0044361047f947cbe818a92de904d
BLAKE2b-256 checksum
How to use checksums
38990655f29250cfada140050030c3a760fc3788bef55d3f8f44d52ee9793822
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.10

Release files / droid_agent-0.1.0-py3-none-any.whl

Download URL droid_agent-0.1.0-py3-none-any.whl
Size 22.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
0790bfe7b5796e5efb5303f97454ec1c32ceef1ffec26de6e797e7e6ceb68c62
BLAKE2b-256 checksum
How to use checksums
402e72b2f96030ce10a6fdae0b3c693a830f49c5bda7b96cf6505a0655228cad
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.10

Security for droid-agent 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page