🤖 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.
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 —
dumpdistills 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.
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.