The Problem

Developers need a way to script interactions with real Android/iOS devices (or their emulators) using natural‑language instructions. Existing mobile‑automation tools require low‑level UI scripting; bridging that gap with LLMs is still ad‑hoc, leading to fragile, hard‑to‑maintain workflows.

What This Does

droidrun implements a LLM‑agnostic agent layer that translates natural‑language commands into device actions. Core agents live under droidrun/agent/ – e.g. droidrun/agent/droid/droidagent.py for Android/iOS control, droidrun/agent/manager/manageragent.py for planning, and droidrun/agent/codeact/codeactagent.py for code‑generation tasks.

The CLI (droidrun/cli/main.py) exposes a droidrun command that loads a configuration (droidrun/configexample.yaml), selects an LLM provider via droidrun/agent/utils/llmpicker.py, and runs the selected agent. Documentation in docs/ (MDX) describes the architecture, prompt design, and the “macro” subsystem (droidrun/macro/) for reusable command sequences.

How To Use It

Setup – Install the package with optional provider extras (as shown in the README):

pip install 'droidrun[google,anthropic,openai,deepseek,ollama,dev]'

If you prefer container isolation, build the Docker image defined in Dockerfile:

docker build -t droidrun:latest .

Configuration – Copy the example config and edit credentials:

cp droidrun/configexample.yaml droidrun/config.yaml cp droidrun/config/credentialsexample.yaml droidrun/credentials.yaml edit droidrun/credentials.yaml with your LLM API keys

Key sections are llm (provider name, model, API key) and device (ADB connection details). The loader in droidrun/configmanager/configmanager.py reads these files at runtime.

Running – The entry point is the module droidrun.main. From a shell:

python -m droidrun # starts the interactive CLI or, using the installed console script (if the package registers it) droidrun --config droidrun/config.yaml "Open Gmail and draft a reply"

For macro replay:

python -m droidrun.macro.replay path/to/macro.json

All commands rely on the droidrun/cli/main.py parser, which forwards the natural‑language request to the appropriate agent.

Real‑World Use

A CI pipeline could invoke droidrun to verify a newly‑released mobile app:

.github/workflows/ci.yml (illustrative) name: Install run: pip install 'droidrun[openai]' name: Start device run: adb start-server && adb devices name: Run smoke test run: | droidrun --config droidrun/config.yaml \ "Launch the app, log in with test user, verify the home screen appears"

The agent translates the sentence into UI actions, captures screenshots, and reports success/failure via the built‑in telemetry (droidrun/telemetry/).

Code Health & Issues

Medium – Untested code paths – No tests/ directory; CI runs linting (black.yml) but no unit or integration tests. Low – Dependency reproducibility – pyproject.toml lists dependencies; a lock file (uv.lock) exists, mitigating version drift. Low – Limited CI coverage – Workflows cover linting, Docker build, and publishing, but no automated functional validation. Low – Configuration secrets – Example credential file (credentialsexample.yaml) is present, but real keys must be supplied manually; no secret‑management integration. Info – License – LICENSE file present, indicating open‑source distribution. Info – Documentation – 60 MDX files provide extensive guides, architecture diagrams, and versioned docs (v1‑v3).

Overall the repository follows a clean modular layout, with clear separation between agents, utilities, and CLI. The presence of setup.py and pyproject.toml shows a standard packaging approach.

The Bottom Line

droidrun delivers a ready‑to‑use Python framework that bridges LLM prompting and mobile device automation, suitable for teams that already manage device labs and need a programmable natural‑language layer. The codebase is well organized and documented, but the lack of automated tests means production adoption should be paired with a custom test harness to validate critical workflows.