Skip to main content

Android Emu Agent

PyPI Python CI License: MIT

Android Emu Agent lets a coding agent inspect and control an Android emulator or device. It provides a command-line interface (CLI) backed by a local daemon.

The daemon reads the current screen, assigns short refs such as ^g1a1 to UI elements, performs actions, and can check the result. This gives an agent a repeatable loop:

observe the screen -> act on a known element -> verify the result -> save evidence

Documentation | Installation | Agent Skills | CLI reference

Quickstart

You need Python 3.11 or later, adb on PATH, and a connected emulator or device.

Install the CLI:

uv tool install android-emu-agent    # or: pipx install android-emu-agent

Give your coding agent the bundled skill, so it knows how to drive the CLI:

npx skills add alehkot/android-emu-agent          # Claude Code, Codex, Cursor, and more
android-emu-agent skills install --agent claude   # same thing, without Node

Then ask your agent for what you want:

Use Android Emu Agent to open Settings on emulator-5554 and verify that Wi-Fi is enabled.

To drive it yourself:

android-emu-agent daemon start
android-emu-agent device list
android-emu-agent session start --device emulator-5554 --json
android-emu-agent ui snapshot <session-id> --format text
android-emu-agent action tap <session-id> ^g1a1
android-emu-agent expect exists <session-id> --text "Wi-Fi" --timeout-ms 5000

uvx android-emu-agent --help works for a quick look, but install persistently before running the daemon: it outlives the command that started it, and uvx builds a fresh temporary environment each time. Full setup, including the guided first loop, is in the installation guide.

Use It With a Coding Agent

The repository ships an Agent Skill that teaches an agent how to use Android Emu Agent: which command to reach for, how to run the observe-act-verify loop, how to recover from a failed action instead of retrying blindly, when to ask before destructive actions, and how to triage crashes and ANRs.

The skill is included in the Python package, so any install already has it. Pick either installer:

npx skills add alehkot/android-emu-agent -a claude-code -g
android-emu-agent skills install --agent claude      # ~/.claude/skills
android-emu-agent skills install --agent codex       # ~/.codex/skills
android-emu-agent skills install --agent claude --project   # .claude/skills, shared with your team
android-emu-agent skills install --dir <path>        # any other agent

Check what is installed with android-emu-agent skills list, and re-run skills install after upgrading the CLI. See the Agent Skills guide for the full list of destinations and example prompts.

Why Use Android Emu Agent?

Raw adb commands and coordinate taps do not describe the current screen. They also do not confirm that an action produced the expected result. Android Emu Agent adds observable targets, checks, and failure evidence to Android automation.

Task Support
Inspect the current screen Compact UI snapshots with refs such as ^g1a1
Tap, type, swipe, and navigate Refs, text and resource selectors, coordinates, and device capabilities
Wait for a state change Wait commands and pass/fail expectations
Repeat an app flow JSON task files and human-editable .aea scripts
Investigate a failure Screenshots, logs, trace archives, and artifact bundles
Debug an app below the UI Kotlin bridge for Java Debug Interface (JDI) commands
Integrate with an agent JSON output, daemon-backed sessions, and a bundled agent skill

Choose the Next Task

Goal Start here
Install the CLI and run the first loop Installation
Set up a coding agent Agent Skills
Follow complete workflow examples Workflow examples
Write a reusable Android flow Task script guide
Look up .aea syntax .aea task script specification
Find an exact CLI option Generated CLI reference
Understand sessions, refs, selectors, and traces Core Concepts

Core Concepts

Snapshots, Refs, and Selectors

A UI snapshot describes the current screen. The snapshot assigns a ref, such as ^g1a1, to each actionable element. In that token, g1 identifies snapshot generation 1 and a1 identifies the first actionable element. Copy the complete ref from the latest snapshot; the element number alone is not stable across snapshots.

Refs belong to one snapshot generation. If the screen changes, take a new snapshot before you use another ref. The daemon can sometimes match a stale ref to the latest snapshot, but it returns a warning when it does this.

You can also select an element by text, resource ID, content description, coordinates, or a combined selector:

^g1a1
text:"Sign in"
text-contains:"Continue"
id:com.example:id/login_btn
desc:"Open navigation"
coords:540,1200
text:"Sign in" || id:com.example:id/login_btn
text:"Continue" enabled:true clickable:true

To see the selector forms and device features available to an automation planner, run android-emu-agent device capabilities --session <session-id> --json.

Sessions

The daemon owns device connections and session state. The CLI sends requests to the daemon through the Unix socket at /tmp/android-emu-agent.sock. Each session connects commands to one target device. Start a session before you inspect or control the device, and stop it when the task is complete. See the installation guide for daemon and artifact file locations.

Tasks, Traces, and Evidence

Use a .aea script or JSON task file to repeat a flow, and a trace when you need to reproduce or investigate a failure:

android-emu-agent task validate ./checkout-smoke.aea
android-emu-agent task run ./checkout-smoke.aea --session <session-id> --json

android-emu-agent trace start <session-id> --label checkout-repro
android-emu-agent trace stop <session-id> --output ./artifacts/checkout-repro.aea-trace.zip
android-emu-agent trace replay ./artifacts/checkout-repro.aea-trace.zip --until-failure
android-emu-agent artifact bundle <session-id> --json

Example scripts live in examples/tasks/.

Check Device Support and Safety

An emulator or rooted device provides the most features. Many UI operations also work on a non-root device when adb is connected and uiautomator2 can attach.

These operations usually work without root access:

  • Capture UI snapshots, screenshots, and visual grounding data.
  • Tap, long-tap, enter text, clear text, swipe, scroll, and press system navigation buttons.
  • Run wait and expectation commands.
  • Install, uninstall, launch, stop, reset, or open a link in an app.
  • List, grant, and revoke runtime permissions.
  • Push and pull files in shared storage.
  • Find and list files in shell-readable storage.
  • Push and pull app-private files for debuggable apps via run-as.
  • Collect supported reliability, process, memory, graphics, and performance data.

These operations require root or emulator access:

  • reliability oom-adj
  • reliability pull anr
  • reliability pull tombstones
  • reliability pull dropbox
  • file find and file list for paths the shell user cannot read.
  • file app push and file app pull for apps that do not permit run-as.

Emulator snapshot save and restore commands require an emulator serial such as emulator-5554. A non-emulator serial returns ERR_NOT_EMULATOR.

Debug an App

Debugger commands use a Kotlin bridge to connect the Java Debug Interface (JDI) to a debuggable Android app. These commands require JDK 17 or later. They also require an app built with android:debuggable=true, or a userdebug or eng target that permits debugging.

The daemon downloads the matching bridge JAR on first use and verifies its checksum.

Use this minimal debugger flow:

android-emu-agent debug ping <session-id>
android-emu-agent app launch <session-id> com.example.app --wait-debugger
android-emu-agent debug attach --session <session-id> --package com.example.app --keep-suspended
android-emu-agent debug break set com.example.app.MainActivity 42 --session <session-id>
android-emu-agent debug resume --session <session-id>
android-emu-agent debug events --session <session-id>
android-emu-agent debug detach --session <session-id>

Troubleshoot a Connection or Action

Start with these checks:

android-emu-agent device list
adb devices
android-emu-agent daemon status --json

Structured daemon errors report a code and a remediation hint. Request-validation failures (for example, an unsupported reliability compile --mode) instead include field-level detail and exit with status 1, including with --json. Correct the rejected arguments before retrying; JSON output preserves the daemon's validation details and diagnostic ID. The installation guide lists every error code and its next action.

Understand the Architecture

CLI client
  -> FastAPI daemon over /tmp/android-emu-agent.sock
    -> sessions, snapshots, actions, waits, expectations, tasks, traces, and artifacts
    -> adbutils and uiautomator2 for device communication
    -> Kotlin JDI Bridge process for debugger commands
      -> Android emulator or device

The CLI is a thin client. The daemon keeps device connections and session state, then sends device commands through adbutils and uiautomator2. Debugger commands use a separate Kotlin process.

Develop Android Emu Agent

Clone the repository and install all project dependencies:

git clone https://github.com/alehkot/android-emu-agent.git
cd android-emu-agent
uv sync --all-extras

Inside the checkout, run the CLI as uv run android-emu-agent <command> so it uses the project environment and your local changes take precedence over any installed release.

Use ./scripts/dev.sh as the main entry point for local development.

Command Purpose
./scripts/dev.sh setup Install dependencies
./scripts/dev.sh check Run format/lint, typing, Python/Kotlin tests, docs, and skill checks
./scripts/dev.sh test-unit Run unit tests
./scripts/dev.sh test-integration Run tests that require an emulator or device
./scripts/dev.sh build-bridge Build the JDI Bridge JAR
./scripts/dev.sh test-bridge Run Kotlin bridge tests
./scripts/dev.sh docs-gen Regenerate docs/reference.md
./scripts/dev.sh docs Build the documentation site in site/
./scripts/dev.sh md Format and lint Markdown
./scripts/dev.sh skills Symlink the bundled skill into local agent directories
./scripts/dev.sh skills-validate Validate the bundled skill metadata and references

docs/reference.md is generated from the CLI. Run ./scripts/dev.sh docs-gen instead of editing its command tables by hand. The documentation site navigation is defined in mkdocs.yml.

License

Android Emu Agent uses the MIT License. See the license.

Metadata

Release files for android-emu-agent 0.2.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for android-emu-agent 0.2.2
File Size Uploaded Provenance Actions
android_emu_agent-0.2.2.tar.gz 186.2 kB Without provenance Details for android_emu_agent-0.2.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for android-emu-agent 0.2.2
File Interpreter ABI Platform Actions
android_emu_agent-0.2.2-py3-none-any.whl Python 3 none any Details for android_emu_agent-0.2.2-py3-none-any.whl

Total release size: 416.8 kB

Release files / android_emu_agent-0.2.2.tar.gz

Download URL android_emu_agent-0.2.2.tar.gz
Size 186.2 kB
Tags Source
SHA-256 checksum
How to use checksums
7be63c93d4ff1ce3c40e2adb766995eb7d94d7b73cad1de453230a0b246b8011
BLAKE2b-256 checksum
How to use checksums
a4dbae42d4fc9292f8d719ff86d4bceb2a524e693bb1882cf8c1b7d586fdf324
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.9

Release files / android_emu_agent-0.2.2-py3-none-any.whl

Download URL android_emu_agent-0.2.2-py3-none-any.whl
Size 230.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
555b458c089c7924ff4afc9b0bfb629ef900cee81d5281b74548e5b49cc8e16c
BLAKE2b-256 checksum
How to use checksums
f85611884bebc5110130d869c86ef3d70f49e441a160c04c11e24ecae2c8eb68
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.9

Security for android-emu-agent 0.2.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page