droid-agent
by hyusband
README.md
<div align="center">
# π€ 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.
[](https://github.com/hyusband/droid-agent/actions/workflows/ci.yml)
[](https://pypi.org/project/droid-agent/)
[](https://pypi.org/project/droid-agent/)
[](LICENSE)

</div>
## 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
```bash
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](https://developer.android.com/tools/releases/platform-tools)
(`adb`) on your `PATH`, and a device with USB or wireless debugging enabled.
## 60-second tour
```bash
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:
```text
[ 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>`
```
```bash
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)
```json
{
"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
```text
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`](https://github.com/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](CONTRIBUTING.md). Bug reports and false-positive
element-detection reports especially welcome β attach `droid-agent dump --json`
plus a screenshot.
## License
MIT β see [LICENSE](LICENSE).
---
<div align="center">
If this saved you a setup afternoon β drop a β
</div>
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues