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.
- droid_agent-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml +43 -0
- droid_agent-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml +23 -0
- droid_agent-0.1.0/.github/pull_request_template.md +16 -0
- droid_agent-0.1.0/.github/workflows/ci.yml +72 -0
- droid_agent-0.1.0/.gitignore +20 -0
- droid_agent-0.1.0/CHANGELOG.md +20 -0
- droid_agent-0.1.0/CONTRIBUTING.md +52 -0
- droid_agent-0.1.0/LICENSE +21 -0
- droid_agent-0.1.0/PKG-INFO +191 -0
- droid_agent-0.1.0/README.md +158 -0
- droid_agent-0.1.0/assets/demo.gif +0 -0
- droid_agent-0.1.0/docs/SHOW_HN.md +34 -0
- droid_agent-0.1.0/examples/agent_session.md +82 -0
- droid_agent-0.1.0/pyproject.toml +57 -0
- droid_agent-0.1.0/scripts/make_demo_gif.py +273 -0
- droid_agent-0.1.0/src/droid_agent/__init__.py +3 -0
- droid_agent-0.1.0/src/droid_agent/__main__.py +4 -0
- droid_agent-0.1.0/src/droid_agent/actions.py +147 -0
- droid_agent-0.1.0/src/droid_agent/adb.py +198 -0
- droid_agent-0.1.0/src/droid_agent/cli.py +404 -0
- droid_agent-0.1.0/src/droid_agent/device.py +130 -0
- droid_agent-0.1.0/src/droid_agent/mcp_server.py +117 -0
- droid_agent-0.1.0/src/droid_agent/output.py +41 -0
- droid_agent-0.1.0/src/droid_agent/session.py +108 -0
- droid_agent-0.1.0/src/droid_agent/ui.py +288 -0
- droid_agent-0.1.0/tests/fixtures/login_dump.xml +20 -0
- droid_agent-0.1.0/tests/test_actions.py +68 -0
- droid_agent-0.1.0/tests/test_cli.py +32 -0
- droid_agent-0.1.0/tests/test_session.py +38 -0
- droid_agent-0.1.0/tests/test_ui.py +75 -0
- 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
|
+
[](https://github.com/hyusband/droid-agent/actions/workflows/ci.yml)
|
|
43
|
+
[](https://pypi.org/project/droid-agent/)
|
|
44
|
+
[](https://pypi.org/project/droid-agent/)
|
|
45
|
+
[](LICENSE)
|
|
46
|
+
|
|
47
|
+

|
|
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
|
+
[](https://github.com/hyusband/droid-agent/actions/workflows/ci.yml)
|
|
10
|
+
[](https://pypi.org/project/droid-agent/)
|
|
11
|
+
[](https://pypi.org/project/droid-agent/)
|
|
12
|
+
[](LICENSE)
|
|
13
|
+
|
|
14
|
+

|
|
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.
|