Controle Android via ADB
hah23255/adb-android-control
Controle completo de dispositivos Android via ADB com tipos, testes e CLI
Ver no GitHubPacote Python tipado com CLI e skill para Claude que envolve o binário `adb` com uma API limpa e testada. Permite controlar dispositivos Android — capturar screenshots, monitorar logs, executar workflows de automação — tanto como biblioteca Python quanto ferramenta CLI ou skill do Claude.
Instalação
npx convez-ai hah23255/adb-android-control1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Automação de testes em dispositivos Android via CI/CD
- Captura de screenshots e monitoramento de logcat em tempo real
- Workflows de teste repetitivos via JSON ou Python API
- Integração com agentes Claude para tarefas mobile
Veredito

Ferramenta sólida e bem testada (1.59:1 teste/código) para quem precisa controlar Android programaticamente. Excelente para CI/CD e integração com Claude, mas exige `adb` instalado e conhecimento básico de Android. Type-safe e production-ready.
README
A tradução para o português deste README ainda está na fila.
adb-android-control
Comprehensive Android device control via ADB — for humans, agents, and CI.
A typed Python package + CLI that wraps the standard adb binary with
a clean, doctrine-tested API. Pairs with Claude Code as a
marketplace skill, but works equally well as a plain Python library or
shell tool.
30-second pitch
pip install adb-android-control
adb-control devices
adb-control info -s EMULATOR-1
adb-control shot screen.png
adb-control monitor logcat
adb-control workflow ./my-test.json
Built around three principles:
- Behavioural test contracts. Every public method has a typed test exercising the failure mode it claims to handle. 338 tests today, 1.59 : 1 test/code ratio.
- No hidden subprocess interleaving. Every shell-out goes through
ADBController(or one flagged streaming carve-out). Noshell=Trueanywhere. Argv lists only. - Observable contracts. Typed exceptions, frozen value objects, wire-format-stable enum values. If we change a public name, your tests will tell you.
Install
As a Python package
# From source (PyPI publish pending)
pip install -e ".[dev]"
# Or just the runtime dependencies
pip install -e .
As a Claude Code skill
git clone https://github.com/hah23255/adb-android-control.git \
~/.claude/skills/adb-android-control
claude /plugin marketplace add ~/.claude/skills/adb-android-control
Quickstart
1. Verify your adb is available
adb version
If this fails, install Android platform-tools or pkg install android-tools on Termux.
2. Connect a device
USB
adb devices # Authorize on the device when prompted
Wireless (Android 11+)
adb pair <device-ip>:<pair-port> <pair-code>
adb connect <device-ip>:<connect-port>
See docs/SETUP.md for screenshots of the device-side
flow.
3. Use it
Python
from adb_android_control import ADBController, DeviceOfflineError
ctrl = ADBController() # raises ADBNotFoundError if adb missing
print(ctrl.devices()) # → list of dicts
info = ctrl.get_device_info() # → DeviceInfo
print(f"{info.model} on Android {info.android_version}")
ctrl.screenshot("/tmp/shot.png")
CLI
adb-control devices # list connected devices
adb-control info # JSON device snapshot
adb-control shot # screenshot.png in $CWD
adb-control monitor logcat -l W # warning+ logcat stream
adb-control monitor crash # crash detector
adb-control radio # WiFi + Bluetooth status
adb-control workflow ./test.json # run an automation workflow
adb-control health # JSON health check
adb-control --version # 2.0.0
4. Author a workflow
{
"steps": [
{ "action": "wake", "delay": 0.5 },
{ "action": "home", "delay": 0.5 },
{ "action": "start_app", "params": {"package": "com.example.app"}, "delay": 3 },
{ "action": "tap_center", "delay": 1 },
{ "action": "screenshot", "params": {"path": "after_tap.png"}, "delay": 0 }
]
}
adb-control workflow my-test.json
22 step kinds available — see
adb_android_control/automation.py.
Architecture
flowchart LR
CLI["adb-control<br/>(cli.py)"] --> Ctrl["ADBController<br/>(controller.py)"]
CLI --> Mon["LogcatMonitor<br/>PerformanceMonitor<br/>CrashMonitor"]
CLI --> Auto["ADBAutomation<br/>AppTester<br/>DeviceManager"]
CLI --> Radio["RadioScanner"]
CLI --> Conn["ConnectionMonitor"]
CLI --> Port["PortScanner"]
Mon --> Ctrl
Auto --> Ctrl
Radio --> Ctrl
Conn --> Ctrl
Ctrl -.subprocess.-> ADB["adb (CLI)"]
ADB -.TCP/USB.-> Device["Android device"]
style Ctrl fill:#0066cc,color:#fff
style CLI fill:#009933,color:#fff
The full architecture deep-dive lives at
docs/ARCHITECTURE.md, including
sequence + state-machine diagrams.
Why this exists
Most Android automation libraries are either:
- Java/Kotlin (e.g. libadb-android) — great for Android-app-internal usage, no help on the host.
- uiautomator2 / Appium — focused on UI test automation; heavyweight install; not great for raw ADB control.
- Pure shell scripts — fragile parsing; hard to test; brittle.
adb-android-control is the missing piece: a typed, doctrine-tested
Python wrapper for everything adb can do, with sane error
classification and zero hidden state.
Testing — the Master Tester Doctrine
This project is governed by the Master Tester Doctrine (HH directive
2026-03-05). The 10 non-negotiable laws live at
docs/TESTING_DOCTRINE.md. Highlights:
| Law | Mechanism in this repo |
|---|---|
| 1. Never modify a test to fix CI | pre-commit + CI test-file-integrity gate (Phase 7) |
| 6. Never mock subprocess directly | Poison-Pill mock_adb fixture in tests/conftest.py |
7. Ban as any in tests | mypy --strict with disallow_any_explicit = true |
| 8. Tests must be deterministic | freezegun, _sleep/_now indirection, no real timers |
Run the tests
pytest # 338 tests; ~10-20K Hypothesis examples
pytest -m unit # unit only (default)
pytest -m property # property-based fuzzing
pytest -m race # threading + concurrency
pytest --cov # coverage report
Project status
| Phase | Status |
|---|---|
| 0. Security purge | ✅ v1.0.1 shipped |
| 1. Test foundation + 8 modules | ✅ phase-1b-complete |
| 2. Code quality + CLI | ✅ phase-2-complete |
| 3. Hypothesis + race + failure injection | ✅ phase-3-complete |
| 4. Documentation | ✅ shipped with v2.0 GA |
| 5. Discoverability | ✅ shipped with v2.0 GA |
| 6. Visual polish (logo + GIFs) | 🟡 in progress |
| 7. CI matrix + Codecov + CodeQL | ✅ shipped with v2.0 GA |
| 8. v2.0 GA | ✅ 2026-05-05 🚀 |
Public GA shipped 2026-05-05 (v2.0.0 — see CHANGELOG).
Roadmap and per-release deliverables are tracked in CHANGELOG.md.
Documentation
| Doc | Audience |
|---|---|
docs/ARCHITECTURE.md | New contributors |
docs/TESTING_DOCTRINE.md | Anyone writing tests |
SECURITY.md | Vulnerability reporters |
docs/MIGRATING.md | Users on v1.0.x |
docs/SETUP.md | First-time setup |
docs/TROUBLESHOOTING.md | When things go wrong (decision tree) |
docs/USE_CASES.md | Recipe gallery |
docs/TUTORIALS.md | Step-by-step walkthroughs |
CHANGELOG.md | Release history |
CONTRIBUTING.md | Contributors |
Contributing
PRs welcome — see CONTRIBUTING.md for the
doctrine-aligned workflow.
License
MIT — see LICENSE.