Ask the local LM Studio VLM about images or a video already on disk.

Args: question: What to ask about the media. images: Paths to image files. video: Path to a video file, sampled into frames. fps: Frames per second when sampling a video. max_frames: Cap on frames sent. model: LM Studio model id; defaults to the configured one.

Check a claim about the current screen using the local VLM. Returns PASS or FAIL.

A cheap oracle: the screenshot goes to LM Studio, not into your context.

Args: question: A yes/no claim, e.g. "is the timed-apps list visible?" device: Device serial; defaults to the first physical device. model: LM Studio model id; defaults to the configured one.

Build the project with Gradle, safely alongside Android Studio, and explain any failure.

ALWAYS use this instead of running gradlew in a terminal: an agent terminal runs Gradle in a sandboxed daemon that keeps R.jar locked against Android Studio. This tool runs the build in Android Studio's own daemon pool, waits if Studio is building, and names any process holding a locked file.

On failure the result is a complete report: category, every compiler/resource error with its file, line and surrounding source, Gradle's explanation, recently changed files, and the path of a self-contained markdown brief you can hand to a fixer subagent.

Args: project_dir: Gradle root (the folder containing settings.gradle[.kts] and gradlew). module: App module, used to derive the default task and find the APK. variant: Build variant, e.g. debug or freeDebug. tasks: Explicit Gradle tasks. Default "::assemble". For a fast compile-only check use [":app:compileDebugKotlin"]. install: Install the built APK on the device afterwards. device: Device serial for install; defaults to the first physical device. release_locks: Stop IDLE Gradle/Kotlin daemons that hold this project's build outputs (e.g. one left behind by an agent terminal). Never touches busy builds. allow_uninstall: If install hits a signature/version conflict, uninstall first (wipes data). wait_if_busy_s: How long to wait for a busy Android Studio daemon before giving up. timeout_s: Build time limit.

Show recent crashes and ANRs (Java exceptions, native signals, not-responding) with stack traces.

App stack frames are mapped to your source files with the surrounding lines, and a self-contained markdown brief is written for a fixer subagent.

Args: package: Only this app's crashes. Defaults to the package of the current session. project_dir: Gradle root, to map stack frames to source. Defaults to the session's. device: Device serial; defaults to the first physical device. only_new: Only crashes since the last check (interaction tools check automatically). max_crashes: How many of the most recent crashes to show.

List attached Android devices and bootable emulator AVDs.

Shows which device the other tools will use by default (first physical device, or ANDROID_AGENT_DEVICE if set). Call this first when unsure what is connected.

Boot an emulator AVD and wait until it is ready.

Args: avd: AVD name as listed by android_devices. wait: Block until sys.boot_completed is set. timeout: Max seconds to wait for boot.

List Gradle and Kotlin daemons, show which ones lock a project's build outputs, optionally stop some.

Explains the classic "R.jar is being used by another process": an idle daemon from a different Gradle user home (e.g. an agent terminal's sandbox) keeps build outputs open.

Args: project_dir: Gradle root whose build outputs to check for locks. stop: None (just list), "lockers" (IDLE daemons holding this project's outputs), "foreign" (IDLE daemons outside Android Studio's Gradle user home - Studio can never reuse them), or "all-idle". Busy daemons and the IDE are never stopped.

Install an already-built APK (no Gradle involved).

Args: project_dir: Gradle root; the APK is found from the module's build outputs. apk: Explicit APK path instead of project_dir. module: App module inside project_dir. variant: Build variant whose APK to install. device: Device serial; defaults to the first physical device. allow_uninstall: On signature/version conflicts, uninstall first (WIPES APP DATA). grant_permissions: Grant all runtime permissions at install time (-g).

Press a hardware/system key.

Args: key: BACK, HOME, ENTER, TAB, DEL, APP_SWITCH, MENU, POWER, VOLUME_UP, ... The KEYCODE_ prefix is added automatically, and a raw keycode number also works. device: Device serial; defaults to the first physical device. screenshot: Return a screenshot of the result. scale: Long-edge px for that screenshot.

Read recent logcat, scoped to one app's process by default.

For crashes and ANRs prefer android_crashes, which also maps stack frames to source.

Args: package: Scope to this app's pid. Omit for all output. device: Device serial; defaults to the first physical device. lines: How many trailing lines to return. grep: Case-insensitive substring filter applied after retrieval. clear_first: Clear the buffer instead of reading (returns immediately).

Grant the special permissions that pm grant cannot, so an app is actually testable.

Sets usage-stats and overlay appops, grants POST_NOTIFICATIONS, and optionally enables an accessibility service. Safe to call repeatedly.

Args: package: App package id, e.g. com.example.app device: Device serial; defaults to the first physical device. accessibility_service: Fully-qualified service, e.g. com.x/.service.MyService

Start recording the screen. Interact normally, then call android_record_stop.

Args: device: Device serial; defaults to the first physical device. max_seconds: Hard stop (device caps this at 180s). size: Optional WxH, e.g. "720x1560", to shrink the capture.

Stop a recording, then have the local VLM describe what happened.

The video is sampled into frames and sent to LM Studio, so a 60s recording comes back as a paragraph instead of flooding your context with images.

Args: handle: The id returned by android_record_start. analyze: Question for the VLM. Defaults to a general description of the interaction. fps: Frames sampled per second of video. max_frames: Cap on frames sent to the model. model: LM Studio model id; defaults to the configured one.

Capture the screen and return it as an image you can look at directly.

Args: device: Device serial; defaults to the first physical device. scale: Long-edge px for the returned image (full-res is saved to disk regardless). analyze: Optional question - also runs the shot through the local LM Studio VLM and attaches its text answer.

Start a driving session: optionally build+install, launch the app, and return the first look.

This is the main entry point. Returns a screenshot (as an image you can see directly) plus the UI dump. If the build fails you get the full build report; if the app crashes on launch you get the stack trace mapped to source instead of a screenshot of the launcher.

Args: package: App package id, e.g. com.example.app activity: Launch activity; resolved automatically if omitted. device: Device serial; defaults to the first physical device. project_dir: Gradle project root. Needed for reinstall, and lets crash stack traces be mapped to source files. reinstall: Build with android_build and install the result first. fresh: pm clear the app first, wiping its data for a clean run. module, variant: Which APK to build/install. release_locks, allow_uninstall: Passed through to the build/install (see android_build). scale: Long-edge px for the returned screenshot.

Swipe or scroll, either by direction or by explicit coordinates.

Args: direction: One of up, down, left, right - a scroll gesture sized to the screen. "down" scrolls content downward (finger moves up). x1, y1, x2, y2: Explicit start/end points, used when direction is omitted. duration_ms: Gesture duration; longer is gentler. device: Device serial; defaults to the first physical device. screenshot: Return a screenshot of the result. scale: Long-edge px for that screenshot.

Tap the screen, by ref from a dump, by visible text, or by raw coordinates.

Args: ref: Ref from android_ui_dump, e.g. "n7". Re-resolved if the dump went stale. text: Visible text or content-desc to match instead of a ref. x, y: Raw coordinates (use when the hierarchy exposes nothing tappable). device: Device serial; defaults to the first physical device. screenshot: Return a screenshot of the result. scale: Long-edge px for that screenshot.

Type text into the focused field, optionally tapping a field first.

ASCII only - adb's input text cannot send unicode.

Args: text: The text to type. ref: Optional ref to tap first, to focus that field. device: Device serial; defaults to the first physical device. submit: Press ENTER afterwards. screenshot: Return a screenshot of the result. scale: Long-edge px for that screenshot.

Dump the on-screen accessibility hierarchy as a table of tappable refs.

Each row gives a ref (n1, n2, ...) usable with android_tap, plus text, content-desc, class, centre point and bounds. Prefer this over guessing pixel coordinates.

Note: Jetpack Compose apps usually expose no resource-ids - match on text/content-desc. If a screen returns no nodes, fall back to android_screenshot and tap by x/y.

Args: device: Device serial; defaults to the first physical device. compact: Show only interactive/labelled nodes (recommended).

Show which local-model (LM Studio) calls were made, by which tool, and what the model saw and said.

Every call from any host (Cursor, Claude Code) or run is recorded in ~/.android-agent/vlm-calls.jsonl, and the exact images sent to the model are saved next to it. Only android_screenshot(analyze=...), android_assert, android_record_stop and android_analyze use the local model - nothing else does.

Args: last: How many of the most recent calls to show. call: Show one call in full, by id ("v3") or "run/id" ("run-20260922-173012/v3"). full: Show full prompts and answers instead of the first lines.

Wait for a fixed delay, or until some text appears or disappears.

Use this instead of screenshotting into the middle of an animation.

Args: ms: Fixed sleep in milliseconds. until_text: Poll until this text/content-desc is present. until_gone: Poll until this text/content-desc is absent. timeout_ms: Give up after this long when polling. device: Device serial; defaults to the first physical device.