droid-agent 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (31) hide show
  1. droid_agent-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml +43 -0
  2. droid_agent-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml +23 -0
  3. droid_agent-0.1.0/.github/pull_request_template.md +16 -0
  4. droid_agent-0.1.0/.github/workflows/ci.yml +72 -0
  5. droid_agent-0.1.0/.gitignore +20 -0
  6. droid_agent-0.1.0/CHANGELOG.md +20 -0
  7. droid_agent-0.1.0/CONTRIBUTING.md +52 -0
  8. droid_agent-0.1.0/LICENSE +21 -0
  9. droid_agent-0.1.0/PKG-INFO +191 -0
  10. droid_agent-0.1.0/README.md +158 -0
  11. droid_agent-0.1.0/assets/demo.gif +0 -0
  12. droid_agent-0.1.0/docs/SHOW_HN.md +34 -0
  13. droid_agent-0.1.0/examples/agent_session.md +82 -0
  14. droid_agent-0.1.0/pyproject.toml +57 -0
  15. droid_agent-0.1.0/scripts/make_demo_gif.py +273 -0
  16. droid_agent-0.1.0/src/droid_agent/__init__.py +3 -0
  17. droid_agent-0.1.0/src/droid_agent/__main__.py +4 -0
  18. droid_agent-0.1.0/src/droid_agent/actions.py +147 -0
  19. droid_agent-0.1.0/src/droid_agent/adb.py +198 -0
  20. droid_agent-0.1.0/src/droid_agent/cli.py +404 -0
  21. droid_agent-0.1.0/src/droid_agent/device.py +130 -0
  22. droid_agent-0.1.0/src/droid_agent/mcp_server.py +117 -0
  23. droid_agent-0.1.0/src/droid_agent/output.py +41 -0
  24. droid_agent-0.1.0/src/droid_agent/session.py +108 -0
  25. droid_agent-0.1.0/src/droid_agent/ui.py +288 -0
  26. droid_agent-0.1.0/tests/fixtures/login_dump.xml +20 -0
  27. droid_agent-0.1.0/tests/test_actions.py +68 -0
  28. droid_agent-0.1.0/tests/test_cli.py +32 -0
  29. droid_agent-0.1.0/tests/test_session.py +38 -0
  30. droid_agent-0.1.0/tests/test_ui.py +75 -0
  31. droid_agent-0.1.0/tests_adversarial/test_adversarial.py +624 -0
@@ -0,0 +1,43 @@
1
+ name: Bug report
2
+ description: Something broke or misbehaved
3
+ labels: [bug]
4
+ body:
5
+ - type: input
6
+ id: version
7
+ attributes:
8
+ label: droid-agent version
9
+ description: output of `droid-agent --version`
10
+ placeholder: "0.1.0"
11
+ validations:
12
+ required: true
13
+ - type: input
14
+ id: device
15
+ attributes:
16
+ label: Device / Android version
17
+ placeholder: "Pixel 7 / Android 14 · or emulator-5554"
18
+ - type: textarea
19
+ id: command
20
+ attributes:
21
+ label: Command you ran
22
+ placeholder: "droid-agent dump --json"
23
+ validations:
24
+ required: true
25
+ - type: textarea
26
+ id: expected
27
+ attributes:
28
+ label: What should have happened?
29
+ validations:
30
+ required: true
31
+ - type: textarea
32
+ id: actual
33
+ attributes:
34
+ label: What actually happened?
35
+ description: Paste the full output / traceback
36
+ validations:
37
+ required: true
38
+ - type: textarea
39
+ id: dump
40
+ attributes:
41
+ label: dump --json + screenshot
42
+ description: For element-detection bugs, attach `droid-agent dump --json` output and a `droid-agent screenshot` PNG
43
+ render: json
@@ -0,0 +1,23 @@
1
+ name: Feature request
2
+ description: A command, flag, or integration you want
3
+ labels: [enhancement]
4
+ body:
5
+ - type: textarea
6
+ id: problem
7
+ attributes:
8
+ label: What are you trying to do?
9
+ description: The workflow, not the solution — what task can't your agent (or you) complete today?
10
+ validations:
11
+ required: true
12
+ - type: textarea
13
+ id: proposal
14
+ attributes:
15
+ label: Proposed interface
16
+ description: What would the command / flag / MCP tool look like?
17
+ - type: checkboxes
18
+ id: constraints
19
+ attributes:
20
+ label: Constraints check
21
+ options:
22
+ - label: This keeps zero runtime dependencies (stdlib only)
23
+ - label: This needs no on-device install (adb only)
@@ -0,0 +1,16 @@
1
+ ## What & why
2
+
3
+ <!-- one paragraph: the problem this solves -->
4
+
5
+ ## Changes
6
+
7
+ <!-- bullets -->
8
+
9
+ ## Checklist
10
+
11
+ - [ ] `ruff check src tests` clean
12
+ - [ ] `python -m pytest` green
13
+ - [ ] no new runtime dependencies (stdlib only)
14
+ - [ ] `--json` output stays parseable (errors to stderr)
15
+ - [ ] CHANGELOG.md updated under Unreleased
16
+ - [ ] README updated if the CLI surface changed
@@ -0,0 +1,72 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ pull_request:
7
+
8
+ jobs:
9
+ test:
10
+ runs-on: ${{ matrix.os }}
11
+ strategy:
12
+ fail-fast: false
13
+ matrix:
14
+ os: [ubuntu-24.04, windows-latest, macos-latest]
15
+ python: ["3.9", "3.10", "3.11", "3.12", "3.13"]
16
+
17
+ steps:
18
+ - uses: actions/checkout@v4
19
+
20
+ - uses: actions/setup-python@v5
21
+ with:
22
+ python-version: ${{ matrix.python }}
23
+
24
+ - name: Install
25
+ run: pip install -e '.[dev]'
26
+
27
+ - name: Lint
28
+ run: ruff check src tests
29
+
30
+ - name: Test
31
+ run: python -m pytest -q
32
+
33
+ - name: CLI smoke
34
+ shell: bash
35
+ run: |
36
+ droid-agent --version
37
+ droid-agent --help > /dev/null
38
+
39
+ build:
40
+ runs-on: ubuntu-latest
41
+ needs: test
42
+ steps:
43
+ - uses: actions/checkout@v4
44
+ - uses: actions/setup-python@v5
45
+ with:
46
+ python-version: "3.12"
47
+ - name: Build
48
+ run: |
49
+ pip install build
50
+ python -m build
51
+ - name: Check wheel
52
+ run: pip install twine && twine check dist/*
53
+ - uses: actions/upload-artifact@v4
54
+ with:
55
+ name: dist
56
+ path: dist/
57
+
58
+ # PyPI publish runs on GitHub Releases via Trusted Publishing (OIDC).
59
+ # One-time setup: PyPI project -> "publishing" -> add this repo/workflow/env.
60
+ publish:
61
+ runs-on: ubuntu-latest
62
+ needs: build
63
+ if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
64
+ environment: pypi
65
+ permissions:
66
+ id-token: write
67
+ steps:
68
+ - uses: actions/download-artifact@v4
69
+ with:
70
+ name: dist
71
+ path: dist/
72
+ - uses: pypa/gh-action-pypi-publish@release/v1
@@ -0,0 +1,20 @@
1
+ __pycache__/
2
+ *.py[cod]
3
+ *.egg-info/
4
+ .eggs/
5
+ build/
6
+ dist/
7
+ .venv/
8
+ venv/
9
+ .pytest_cache/
10
+ .ruff_cache/
11
+ .mypy_cache/
12
+ htmlcov/
13
+ .coverage
14
+ .DS_Store
15
+ Thumbs.db
16
+ *.log
17
+
18
+ # raw device screencaps used to build the demo (may contain personal data)
19
+ assets/src/
20
+ _log.txt
@@ -0,0 +1,20 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project will be documented in this file.
4
+
5
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
+ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
+
8
+ ## [0.1.0] - 2026-11-19
9
+
10
+ ### Added
11
+ - Core CLI: `devices`, `connect`, `pair`, `disconnect`, `dump`, `tap`,
12
+ `long-press`, `swipe`, `type`, `key`, `wait`, `open`, `close`, `install`,
13
+ `uninstall`, `screenshot`, `state`, `shell`, `mcp`
14
+ - Numbered interactive-element refs distilled from uiautomator XML
15
+ (browser-use-style), persisted per session at `~/.droid-agent/session.json`
16
+ - Stale-ref detection (>120s) with re-dump hint
17
+ - `--json` output mode on every command for agent consumption
18
+ - MCP stdio server (`droid-agent[mcp]` extra) exposing 12 tools
19
+ - Wireless pairing support for Android 11+
20
+ - Password-field masking in dumps
@@ -0,0 +1,52 @@
1
+ # Contributing to droid-agent
2
+
3
+ Thanks for helping! This project stays intentionally small: **zero runtime
4
+ dependencies** and **no device-side installs** are hard constraints — every
5
+ contribution is weighed against them.
6
+
7
+ ## Setup
8
+
9
+ ```bash
10
+ git clone https://github.com/FEKA/droid-agent
11
+ cd droid-agent
12
+ pip install -e '.[dev]'
13
+ python -m pytest
14
+ ```
15
+
16
+ ## Ground rules
17
+
18
+ 1. **No new runtime dependencies.** Everything in `src/droid_agent/` is
19
+ stdlib-only. Optional extras (like `mcp`) live behind extras and must be
20
+ import-guarded.
21
+ 2. **Every failure must be explainable.** If adb/device/user input can fail,
22
+ the error must say *why* and *what to try* — never a bare traceback.
23
+ Raise `AdbError` with a useful message; the CLI turns it into a clean exit.
24
+ 3. **`--json` is a contract.** Agents consume it. Keys are snake_case,
25
+ errors go to stderr, stdout stays parseable. Don't print decoration in
26
+ JSON mode.
27
+ 4. **Refs are sacred.** Element numbering must be deterministic for a given
28
+ hierarchy — tests in `tests/test_ui.py` pin the ordering.
29
+
30
+ ## Testing
31
+
32
+ - Unit tests run without a device: `python -m pytest`
33
+ - Fixtures live in `tests/fixtures/` — add a `uiautomator dump` capture when
34
+ fixing an element-detection bug. Sanitize package names if needed.
35
+ - Adversarial coverage lives in `tests_adversarial/` — breakage found in the
36
+ wild should land there with a repro.
37
+
38
+ ## Pull requests
39
+
40
+ - One change per PR; describe the *why*.
41
+ - Run `ruff check src tests` and `python -m pytest` before pushing.
42
+ - Update `CHANGELOG.md` under an `Unreleased` heading.
43
+ - New CLI flags/commands need README table entries.
44
+
45
+ ## Reporting bugs
46
+
47
+ Open an issue with:
48
+
49
+ - `droid-agent --version`, Android version, device/emulator
50
+ - the exact command you ran
51
+ - `droid-agent dump --json` output + a screenshot if it's a UI-detection bug
52
+ - what you expected vs what happened
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 droid-agent contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,191 @@
1
+ Metadata-Version: 2.5
2
+ Name: droid-agent
3
+ Version: 0.1.0
4
+ Summary: Agent-native Android control over stock adb — numbered UI refs, JSON output, MCP server. No Appium, no on-device APK.
5
+ Project-URL: Homepage, https://github.com/hyusband/droid-agent
6
+ Project-URL: Repository, https://github.com/hyusband/droid-agent
7
+ Project-URL: Issues, https://github.com/hyusband/droid-agent/issues
8
+ Project-URL: Changelog, https://github.com/hyusband/droid-agent/blob/main/CHANGELOG.md
9
+ Author: droid-agent contributors
10
+ License-Expression: MIT
11
+ License-File: LICENSE
12
+ Keywords: adb,agent,android,automation,cli,llm,mcp,uiautomator
13
+ Classifier: Development Status :: 4 - Beta
14
+ Classifier: Environment :: Console
15
+ Classifier: Intended Audience :: Developers
16
+ Classifier: License :: OSI Approved :: MIT License
17
+ Classifier: Operating System :: OS Independent
18
+ Classifier: Programming Language :: Python :: 3
19
+ Classifier: Programming Language :: Python :: 3.9
20
+ Classifier: Programming Language :: Python :: 3.10
21
+ Classifier: Programming Language :: Python :: 3.11
22
+ Classifier: Programming Language :: Python :: 3.12
23
+ Classifier: Programming Language :: Python :: 3.13
24
+ Classifier: Topic :: Software Development :: Testing
25
+ Classifier: Topic :: Utilities
26
+ Requires-Python: >=3.9
27
+ Provides-Extra: dev
28
+ Requires-Dist: pytest>=7.0; extra == 'dev'
29
+ Requires-Dist: ruff>=0.4; extra == 'dev'
30
+ Provides-Extra: mcp
31
+ Requires-Dist: mcp>=1.2.0; extra == 'mcp'
32
+ Description-Content-Type: text/markdown
33
+
34
+ <div align="center">
35
+
36
+ # 🤖 droid-agent
37
+
38
+ **Give any AI agent hands on a real Android device — zero install on the phone.**
39
+
40
+ `dump` a screen → get numbered interactive elements → `tap 3`. That's it.
41
+
42
+ [![CI](https://github.com/hyusband/droid-agent/actions/workflows/ci.yml/badge.svg)](https://github.com/hyusband/droid-agent/actions/workflows/ci.yml)
43
+ [![PyPI](https://img.shields.io/pypi/v/droid-agent)](https://pypi.org/project/droid-agent/)
44
+ [![Python](https://img.shields.io/pypi/pyversions/droid-agent)](https://pypi.org/project/droid-agent/)
45
+ [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
46
+
47
+ ![demo](assets/demo.gif)
48
+
49
+ </div>
50
+
51
+ ## Why
52
+
53
+ Every other Android-agent tool makes you install something **on the phone**
54
+ first — an Appium server, a companion APK, an accessibility service.
55
+ `droid-agent` needs **nothing on the device**. Just `adb`, which you already
56
+ have:
57
+
58
+ - 🔢 **browser-use for Android** — `dump` distills the uiautomator tree into a
59
+ short numbered list of actionable refs, not a 500-line XML blob
60
+ - 📦 **zero dependencies** — pure stdlib, installs in <1s, works offline
61
+ - 🤖 **agent-first** — every command has `--json`; ships a built-in MCP server
62
+ - 📱 **anything with adb** — real phones, emulators, Android TVs, Android Auto,
63
+ WSA, even Android-x86 VMs
64
+
65
+ ## Install
66
+
67
+ ```bash
68
+ pipx install droid-agent # recommended
69
+ # or: pip install droid-agent
70
+
71
+ pipx install 'droid-agent[mcp]' # + MCP server for Claude Code / Cursor / Devin
72
+ ```
73
+
74
+ Prerequisite: [platform-tools](https://developer.android.com/tools/releases/platform-tools)
75
+ (`adb`) on your `PATH`, and a device with USB or wireless debugging enabled.
76
+
77
+ ## 60-second tour
78
+
79
+ ```bash
80
+ droid-agent devices # what's attached
81
+ droid-agent connect 192.168.1.42 # wireless adb (or just plug USB)
82
+ droid-agent dump # see the screen the way an agent does
83
+ ```
84
+
85
+ Real output, straight off a POCO F5:
86
+
87
+ ```text
88
+ [ 1] () Search settings ( 540, 497)
89
+ [ 2] ||| recyclerview ( 540,1487)
90
+ [ 3] () About phone ( 540, 663)
91
+ [ 4] () System apps updater ( 540, 817)
92
+ [ 5] () Security status ( 540, 971)
93
+ [ 6] () Wi-Fi ( 540,1159)
94
+ [ 7] () Bluetooth ( 540,1313)
95
+ [ 8] () Mobile networks ( 540,1467)
96
+ [ 9] () Interconnectivity ( 540,1621)
97
+
98
+ 15 elements · tap with `droid-agent tap <ref>`
99
+ ```
100
+
101
+ ```bash
102
+ droid-agent tap 3 # taps "About phone"
103
+ droid-agent type "me@x.com" # types into the focused field
104
+ droid-agent swipe up # scroll the list
105
+ droid-agent key back # keyevents by name
106
+ droid-agent open com.whatsapp # launch any app
107
+ droid-agent screenshot shot.png # PNG capture
108
+ droid-agent state # foreground app, screen on/off, size
109
+ ```
110
+
111
+ For agents, everything is one flag away from JSON: `droid-agent --json dump`.
112
+
113
+ ## Use it with your agent (MCP)
114
+
115
+ ```json
116
+ {
117
+ "mcpServers": {
118
+ "droid-agent": { "command": "droid-agent", "args": ["mcp"] }
119
+ }
120
+ }
121
+ ```
122
+
123
+ Tools exposed: `devices`, `dump_ui`, `tap`, `tap_xy`, `type_text`, `swipe`,
124
+ `key`, `open_app`, `close_app`, `device_state`, `screenshot`, `wait`.
125
+
126
+ ## Commands
127
+
128
+ | Command | What it does |
129
+ | --- | --- |
130
+ | `devices` | list attached devices + state |
131
+ | `connect` / `pair` / `disconnect` | wireless adb (Android 11+ pairing supported) |
132
+ | `dump` | numbered interactive elements → `~/.droid-agent/session.json` |
133
+ | `tap <ref\|x,y>` / `long-press` | touch by ref from last dump, or raw coords |
134
+ | `type <text>` | input text (spaces handled) into focused field |
135
+ | `swipe up\|down\|left\|right` or `x1 y1 x2 y2` | scroll / gestures |
136
+ | `key back\|home\|enter\|tab\|del\|power…` | keyevents by name |
137
+ | `open` / `close` / `install` / `uninstall` | app lifecycle |
138
+ | `screenshot` / `state` | PNG capture · foreground app + screen info |
139
+ | `shell <cmd>` | raw adb escape hatch |
140
+ | `mcp` | stdio MCP server |
141
+
142
+ ## How it compares
143
+
144
+ | | droid-agent | droidrun/mobilerun | mobile-mcp | Appium |
145
+ | --- | --- | --- | --- | --- |
146
+ | On-device install | **none** | Portal APK + accessibility svc | Appium driver | Appium server + settings app |
147
+ | Time to first `tap` | **seconds** | minutes | minutes | ~30 min |
148
+ | What it is | primitive layer | full agent framework | MCP bridge | test framework |
149
+ | Deps | **0** (stdlib) | LLM SDKs, uv, portal | node, appium | java/node stack |
150
+ | LLM coupling | none — BYO agent | built-in providers | none | none |
151
+
152
+ Different tool for a different job: they're agent *frameworks*; this is the
153
+ `curl` of Android control — a primitive layer any agent (or human) can call.
154
+
155
+ ## Agent workflow pattern
156
+
157
+ ```text
158
+ dump → read refs → tap/type → wait → dump → verify → repeat
159
+ ```
160
+
161
+ The dump warns when refs are >120s old (the UI may have moved). `tap` on a
162
+ missing ref tells you to re-dump instead of tapping blind.
163
+
164
+ ## FAQ
165
+
166
+ **Does it need root?** No — just USB/wireless debugging enabled.
167
+
168
+ **iOS?** No. Use [`iphone-cli`](https://github.com/HyunSeob/iphone-cli) — this one is
169
+ Android-only by design.
170
+
171
+ **Passwords?** Elements flagged `password="true"` are masked in dumps and
172
+ never persisted to the session file.
173
+
174
+ **CI?** Point it at an emulator (`emulator-5554`) — same interface, `--json`
175
+ for parsing.
176
+
177
+ ## Contributing
178
+
179
+ See [CONTRIBUTING.md](CONTRIBUTING.md). Bug reports and false-positive
180
+ element-detection reports especially welcome — attach `droid-agent dump --json`
181
+ plus a screenshot.
182
+
183
+ ## License
184
+
185
+ MIT — see [LICENSE](LICENSE).
186
+
187
+ ---
188
+
189
+ <div align="center">
190
+ If this saved you a setup afternoon — drop a ⭐
191
+ </div>
@@ -0,0 +1,158 @@
1
+ <div align="center">
2
+
3
+ # 🤖 droid-agent
4
+
5
+ **Give any AI agent hands on a real Android device — zero install on the phone.**
6
+
7
+ `dump` a screen → get numbered interactive elements → `tap 3`. That's it.
8
+
9
+ [![CI](https://github.com/hyusband/droid-agent/actions/workflows/ci.yml/badge.svg)](https://github.com/hyusband/droid-agent/actions/workflows/ci.yml)
10
+ [![PyPI](https://img.shields.io/pypi/v/droid-agent)](https://pypi.org/project/droid-agent/)
11
+ [![Python](https://img.shields.io/pypi/pyversions/droid-agent)](https://pypi.org/project/droid-agent/)
12
+ [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
13
+
14
+ ![demo](assets/demo.gif)
15
+
16
+ </div>
17
+
18
+ ## Why
19
+
20
+ Every other Android-agent tool makes you install something **on the phone**
21
+ first — an Appium server, a companion APK, an accessibility service.
22
+ `droid-agent` needs **nothing on the device**. Just `adb`, which you already
23
+ have:
24
+
25
+ - 🔢 **browser-use for Android** — `dump` distills the uiautomator tree into a
26
+ short numbered list of actionable refs, not a 500-line XML blob
27
+ - 📦 **zero dependencies** — pure stdlib, installs in <1s, works offline
28
+ - 🤖 **agent-first** — every command has `--json`; ships a built-in MCP server
29
+ - 📱 **anything with adb** — real phones, emulators, Android TVs, Android Auto,
30
+ WSA, even Android-x86 VMs
31
+
32
+ ## Install
33
+
34
+ ```bash
35
+ pipx install droid-agent # recommended
36
+ # or: pip install droid-agent
37
+
38
+ pipx install 'droid-agent[mcp]' # + MCP server for Claude Code / Cursor / Devin
39
+ ```
40
+
41
+ Prerequisite: [platform-tools](https://developer.android.com/tools/releases/platform-tools)
42
+ (`adb`) on your `PATH`, and a device with USB or wireless debugging enabled.
43
+
44
+ ## 60-second tour
45
+
46
+ ```bash
47
+ droid-agent devices # what's attached
48
+ droid-agent connect 192.168.1.42 # wireless adb (or just plug USB)
49
+ droid-agent dump # see the screen the way an agent does
50
+ ```
51
+
52
+ Real output, straight off a POCO F5:
53
+
54
+ ```text
55
+ [ 1] () Search settings ( 540, 497)
56
+ [ 2] ||| recyclerview ( 540,1487)
57
+ [ 3] () About phone ( 540, 663)
58
+ [ 4] () System apps updater ( 540, 817)
59
+ [ 5] () Security status ( 540, 971)
60
+ [ 6] () Wi-Fi ( 540,1159)
61
+ [ 7] () Bluetooth ( 540,1313)
62
+ [ 8] () Mobile networks ( 540,1467)
63
+ [ 9] () Interconnectivity ( 540,1621)
64
+
65
+ 15 elements · tap with `droid-agent tap <ref>`
66
+ ```
67
+
68
+ ```bash
69
+ droid-agent tap 3 # taps "About phone"
70
+ droid-agent type "me@x.com" # types into the focused field
71
+ droid-agent swipe up # scroll the list
72
+ droid-agent key back # keyevents by name
73
+ droid-agent open com.whatsapp # launch any app
74
+ droid-agent screenshot shot.png # PNG capture
75
+ droid-agent state # foreground app, screen on/off, size
76
+ ```
77
+
78
+ For agents, everything is one flag away from JSON: `droid-agent --json dump`.
79
+
80
+ ## Use it with your agent (MCP)
81
+
82
+ ```json
83
+ {
84
+ "mcpServers": {
85
+ "droid-agent": { "command": "droid-agent", "args": ["mcp"] }
86
+ }
87
+ }
88
+ ```
89
+
90
+ Tools exposed: `devices`, `dump_ui`, `tap`, `tap_xy`, `type_text`, `swipe`,
91
+ `key`, `open_app`, `close_app`, `device_state`, `screenshot`, `wait`.
92
+
93
+ ## Commands
94
+
95
+ | Command | What it does |
96
+ | --- | --- |
97
+ | `devices` | list attached devices + state |
98
+ | `connect` / `pair` / `disconnect` | wireless adb (Android 11+ pairing supported) |
99
+ | `dump` | numbered interactive elements → `~/.droid-agent/session.json` |
100
+ | `tap <ref\|x,y>` / `long-press` | touch by ref from last dump, or raw coords |
101
+ | `type <text>` | input text (spaces handled) into focused field |
102
+ | `swipe up\|down\|left\|right` or `x1 y1 x2 y2` | scroll / gestures |
103
+ | `key back\|home\|enter\|tab\|del\|power…` | keyevents by name |
104
+ | `open` / `close` / `install` / `uninstall` | app lifecycle |
105
+ | `screenshot` / `state` | PNG capture · foreground app + screen info |
106
+ | `shell <cmd>` | raw adb escape hatch |
107
+ | `mcp` | stdio MCP server |
108
+
109
+ ## How it compares
110
+
111
+ | | droid-agent | droidrun/mobilerun | mobile-mcp | Appium |
112
+ | --- | --- | --- | --- | --- |
113
+ | On-device install | **none** | Portal APK + accessibility svc | Appium driver | Appium server + settings app |
114
+ | Time to first `tap` | **seconds** | minutes | minutes | ~30 min |
115
+ | What it is | primitive layer | full agent framework | MCP bridge | test framework |
116
+ | Deps | **0** (stdlib) | LLM SDKs, uv, portal | node, appium | java/node stack |
117
+ | LLM coupling | none — BYO agent | built-in providers | none | none |
118
+
119
+ Different tool for a different job: they're agent *frameworks*; this is the
120
+ `curl` of Android control — a primitive layer any agent (or human) can call.
121
+
122
+ ## Agent workflow pattern
123
+
124
+ ```text
125
+ dump → read refs → tap/type → wait → dump → verify → repeat
126
+ ```
127
+
128
+ The dump warns when refs are >120s old (the UI may have moved). `tap` on a
129
+ missing ref tells you to re-dump instead of tapping blind.
130
+
131
+ ## FAQ
132
+
133
+ **Does it need root?** No — just USB/wireless debugging enabled.
134
+
135
+ **iOS?** No. Use [`iphone-cli`](https://github.com/HyunSeob/iphone-cli) — this one is
136
+ Android-only by design.
137
+
138
+ **Passwords?** Elements flagged `password="true"` are masked in dumps and
139
+ never persisted to the session file.
140
+
141
+ **CI?** Point it at an emulator (`emulator-5554`) — same interface, `--json`
142
+ for parsing.
143
+
144
+ ## Contributing
145
+
146
+ See [CONTRIBUTING.md](CONTRIBUTING.md). Bug reports and false-positive
147
+ element-detection reports especially welcome — attach `droid-agent dump --json`
148
+ plus a screenshot.
149
+
150
+ ## License
151
+
152
+ MIT — see [LICENSE](LICENSE).
153
+
154
+ ---
155
+
156
+ <div align="center">
157
+ If this saved you a setup afternoon — drop a ⭐
158
+ </div>
Binary file
@@ -0,0 +1,34 @@
1
+ # Show HN draft — launch copy
2
+
3
+ **Title:** Show HN: droid-agent – control Android via adb, no on-device install
4
+
5
+ **Post:**
6
+
7
+ Every Android automation tool for AI agents asks you to install something on
8
+ the phone first — Appium's server, a companion APK, an accessibility service.
9
+ I wanted the opposite: give an agent hands using only stock adb, which every
10
+ dev/emulator already has.
11
+
12
+ `droid-agent dump` runs `uiautomator dump`, then distills the XML hierarchy
13
+ into a browser-use-style numbered list of *actionable* elements — buttons,
14
+ inputs, scrollables — with stable refs. `droid-agent tap 3` resolves the ref
15
+ to its center point. Re-dump, verify, repeat. The whole thing is ~1k lines of
16
+ stdlib-only Python with `--json` on every command, plus a built-in MCP server
17
+ (`pipx install 'droid-agent[mcp]'`, then one JSON block in your agent config).
18
+
19
+ Design choices that might be interesting:
20
+
21
+ - The ref map persists to disk per session with a staleness timer — tapping a
22
+ ref from a 3-minute-old screen is how agents click the wrong thing, so it
23
+ warns instead.
24
+ - Clickable parents absorb their children's text as the label (a Button
25
+ wrapping a TextView shows as `button "ACTIVAR"`, not two rows).
26
+ - Password fields are masked in dumps so agents don't leak credentials into
27
+ logs.
28
+ - Zero deps and ~300ms startup — meant to be called 50×/session, not once.
29
+
30
+ Works on real phones, emulators, Android TV/x86 — anything adb reaches.
31
+ MIT licensed: https://github.com/FEKA/droid-agent
32
+
33
+ Happy to answer questions; especially curious what element-detection edge
34
+ cases break for you.