android-emu-agent

name

android-emu-agent

description

Observe-act-verify Android emulators or rooted devices with UI snapshots, generation-scoped refs, selector escape hatches, waits, app/system/file commands, reliability forensics, trace artifacts, and debugger flows. Use when asked to inspect an Android screen, interact with an app, run emulator/device UI automation, handle dialogs/forms/navigation, troubleshoot stale or missing elements, capture screenshots/logs/traces, diagnose crashes/ANRs/performance, or use android-emu-agent commands. Do not use for generic Android source-code edits unless a device/emulator automation flow is involved.

Android Emu Agent Skill

Use the android-emu-agent CLI + daemon to control Android UI with actionable snapshots and generation-scoped element refs. Compact snapshots are designed to work well across classic XML layouts and modern frameworks such as Compose and Litho. If you're working inside this repo, prefer uv run android-emu-agent ... to ensure the correct environment.

Operating Process

1. Classify the branch: readiness check, read-only inquiry, action flow, recovery, reliability, debugger, file transfer, or command lookup. Completion: the active branch is named and only the matching reference files from the Decision Guide are loaded.
2. Establish the target: ensure the daemon, device, and session state needed for that branch. Completion: a session_id or device serial is known, or the missing prerequisite is reported.
3. Run the observe-act-verify loop for UI work: fresh snapshot, one action, wait as needed, fresh snapshot or expectation. Completion: the requested state is observed, or the recovery protocol reaches its stated limit.
4. Report the outcome: current package/activity or device state, actions taken, relevant artifacts, diagnostic IDs, and any unresolved blocker.

SDK CLI Prerequisites

• For connected-device workflows, adb must be available.
• For emulator lifecycle workflows, emulator should be available.
• For creating or inspecting AVD definitions outside the agent, avdmanager is recommended.
• The daemon resolves tools from PATH first, then standard Android SDK roots from ANDROID_SDK_ROOT / ANDROID_HOME.

Quick Start

1. Start the daemon.

uv run android-emu-agent daemon start
uv run android-emu-agent daemon status

1. Verify a device is connected.

uv run android-emu-agent device list

1. If no emulator is running, boot one first.

uv run android-emu-agent emulator list-avds
uv run android-emu-agent emulator start <avd_name> --wait-boot

1. Start a session.

uv run android-emu-agent session start --device <serial>
# Returns: session_id = s-abc123

1. Run the observe-act-verify loop.

# Observe
uv run android-emu-agent ui snapshot <session_id>

# Act (one action)
uv run android-emu-agent action tap <session_id> ^a1

# Verify
uv run android-emu-agent ui snapshot <session_id>

Daemon Lifecycle (When and How to Start)

• Start the daemon before any device/session/ui/action/app/reliability/file commands.
• The CLI can auto-start the daemon on first request, but start it explicitly for stable sessions.
• Verify health with uv run android-emu-agent daemon status before long runs.
• Stop it when you are done with uv run android-emu-agent daemon stop.
• If you are working inside this repo, use uv run android-emu-agent ... for all of the above.

Core Rules

• Never act without a user request. When the user starts a session (e.g. "I'm going to use my emulator"), only ensure readiness (daemon up, device connected, session active). Do not tap, swipe, type, launch apps, or take any UI action until the user explicitly asks. See references/behavioral-protocols.md > Session Readiness Check.
• One action per snapshot. Refs are generation-scoped.
• Re-snapshot after any action or wait.
• Verify state changes after each action.
• If blocked by dialogs or loading, handle the blocker first.
• If a stale ref is auto-healed, treat the warning as a prompt to re-snapshot before the next action.
• When an action fails, follow the recovery protocol (re-snapshot, visual analysis, then ask user). Do not blindly retry. See references/recovery.md.
• Confirm before write/destructive actions unless the user explicitly requested them. See references/behavioral-protocols.md > Write-Action Confirmation Protocol.
• Read-only first for informational tasks. When the user asks a question about the UI (e.g. "is there a button for...", "what does this screen show", "check if..."), use only read-only methods (snapshots, screenshots, scrolling) to answer. Do not tap, type, or otherwise modify UI state to investigate. See references/behavioral-protocols.md > Inquiry vs. Action Tasks.
• Missing-elements escalation is mandatory. If the user reports missing/stale/filtered elements (e.g. "snapshot is stale", "components are missing"), automatically run the read-only escalation path in order: fresh compact snapshot → wait idle + compact snapshot → ui snapshot --full → ui snapshot --raw → ui screenshot. Do not stop at compact mode in this case. In the worst case, capture a screenshot, deliver it, and provide visual analysis before asking the user what to do next.

Decision Guide

Load only the branch files needed for the active task. Match your situation to the right file:

• Asked to inspect a screen, answer what is visible, or confirm whether UI exists → references/behavioral-protocols.md first, then references/core-loop.md
• Asked to run an app flow, test scenario, or repeated automation → references/core-loop.md, then references/ui-automation-patterns.md or references/examples.md
• Starting a session or understanding the loop → references/core-loop.md
• Looking up a command or selector syntax → references/command-reference.md
• Handling a UI scenario (permissions, dialogs, login, onboarding, navigation, forms, scrolling) → references/ui-automation-patterns.md
• Deciding whether to act or confirm first (inquiry vs. action, write-action confirmation, unknown elements) → references/behavioral-protocols.md
• Action failed with an error → references/recovery.md
• Hit an error or unexpected behavior → references/troubleshooting.md
• Need a complete end-to-end walkthrough → references/examples.md
• Need targeted workflow examples (visual grounding, trace archive, capabilities, intent preflight, evidence bundle) → references/workflow-examples.md
• Diagnosing a crash, ANR, or process death → references/reliability.md
• Investigating runtime behavior with breakpoints/stack/inspect → references/debugging.md
• Pushing or pulling files to/from device → references/files.md