Orca Emulator — Android (adb / emulator powered)
Drive an Android emulator or adb-connected device from within Orca using
orca emulator ... commands. The Android backend shells out to the Android SDK
(adb, emulator, avdmanager) that Android Studio installs, so it works on
Windows, Linux, and macOS — unlike the iOS backend (orca-emulator), which is
macOS-only. Device control uses adb shell input, so it works without any extra
streaming server.
Status: device discovery + lifecycle + full input/capability control are
live. The embedded 60fps visual pane (scrcpy/H.264) is in development — for
now, watch the device in Android Studio's emulator window while you drive it
from the CLI.
When to use
- List, boot, and target Android emulators/AVDs and physical devices.
- Tap, swipe, type, press hardware buttons (home/back/recents/power/volume),
rotate a running Android device.
- Install an APK, launch an app, grant/revoke runtime permissions.
- Read the accessibility tree (
uiautomator) or capture logcat.
- Run an arbitrary
adb shell command via exec.
When NOT to use
- iOS simulators → use the
orca-emulator skill (macOS only).
- Building the app → use Gradle /
./gradlew assembleDebug, then install.
- Camera/sensor injection → not supported yet (Android virtual-scene is out of
scope for now).
- Remote/SSH device control → out of scope; the SDK + device are local to the host.
Prerequisites (surfaced by Orca)
- Android Studio / Android SDK installed, with
ANDROID_HOME (or
ANDROID_SDK_ROOT) set. Orca also checks the per-OS default location
(%LOCALAPPDATA%\Android\Sdk, ~/Library/Android/sdk, ~/Android/Sdk).
adb + emulator on the SDK path; at least one AVD (create in Android
Studio ▸ Device Manager) or a connected device with USB debugging.- A device that is booted and
adb-visible for input/capability commands
(an AVD that is still shutdown can be listed but must be booted first).
Orca returns a clear message when the SDK is missing
(Android SDK not found. Install Android Studio and set ANDROID_HOME.).
Mental model
┌────────────────────────┐
│ orca CLI (agents) │ e.g. orca emulator tap 0.5 0.7 --device emulator-5554
└───────────┬────────────┘
│ RPC
▼
┌────────────────────────┐ resolves backend by device
│ EmulatorBridge (router)│ ─────────────────────────────► AndroidEmulatorBackend
└────────────────────────┘ │ adb / emulator / avdmanager
▼
Android emulator / device
Orca owns backend routing and the per-worktree active-device registry. The
Android backend converts Orca's normalized 0–1 coordinates to device pixels and
issues adb shell input events; AVD names resolve to running adb serials.
Common operations
Use --json for agent-friendly output. Coordinates are normalized 0..1
(top-left origin) — never pixels; Orca converts using the live screen size.
| Goal |
Command |
Notes |
| List devices + AVDs |
orca emulator devices --json |
Cross-platform; shows iOS + Android with a platform column, booted vs shutdown. |
| Single tap |
orca emulator tap <x> <y> --device <serial> |
Normalized 0..1. Preferred for single taps. |
| Swipe / gesture |
orca emulator gesture '<json>' --device <serial> |
adb approximates the path by its endpoints (start→end). |
| Type text |
orca emulator type "user@example.com" --device <serial> |
US ASCII; spaces handled. No newlines. |
| Hardware button |
orca emulator button back --device <serial> |
home, back, recents, power, volume_up, volume_down. |
| Rotate |
orca emulator rotate landscape_left --device <serial> |
Sets user_rotation (disables auto-rotate). |
| Install an APK |
orca emulator install ./app-debug.apk --reinstall --device <serial> |
--reinstall passes -r. |
| Launch an app |
orca emulator launch com.acme.app --activity .MainActivity --device <serial> |
Omit --activity to launch the default LAUNCHER activity. |
| Grant a permission |
orca emulator permissions grant com.acme.app android.permission.CAMERA --device <serial> |
grant / revoke / reset. |
| Accessibility tree |
orca emulator ax --device <serial> --json |
uiautomator dump parsed to a node tree. |
| Logcat (one-shot) |
orca emulator logcat --lines 200 --device <serial> |
Dumps recent lines; parsed to entries. |
| Raw adb shell |
orca emulator exec --command "getprop ro.build.version.sdk" --device <serial> |
Runs adb -s <serial> shell <command>. |
Critical gotchas (teach agents)
- All coordinates are normalized 0..1 (top-left origin), never pixels — Orca
scales to the device's live resolution.
- Target a running device by its adb serial (e.g.
emulator-5554) shown in
orca emulator devices. An AVD name resolves only once that AVD is booted.
- The device must be booted and adb-visible before input/capability commands;
a shutdown AVD is listed with
state: shutdown and must be started first
(Android Studio, or emulator @<avd>).
type uses adb shell input text — US ASCII, spaces are handled, newlines are
not. For unicode-heavy input, use the app UI directly.gesture is a straight swipe between the first and last point (adb limitation);
fine for scroll/swipe, not for true multi-touch paths.- Capability verbs (
install/launch/permissions/ax/logcat) are Android-only;
running them against an iOS device fails with emulator_unsupported.
- No camera/sensor injection yet.
Targeting devices & worktrees
- Explicit device:
--device <serial> (recommended for Android today) or an AVD
name once booted.
orca emulator devices is global (lists every backend's devices); other verbs
target the resolved device's backend automatically.--worktree <selector> scopes to a worktree's active device once the
attach/active flow lands for Android.
Examples (agent-friendly)
orca emulator devices --json
orca emulator tap 0.5 0.85 --device emulator-5554 --json
orca emulator type "hello world" --device emulator-5554 --json
orca emulator button recents --device emulator-5554 --json
orca emulator install ./app-debug.apk --reinstall --device emulator-5554 --json
orca emulator launch com.acme.app --device emulator-5554 --json
orca emulator permissions grant com.acme.app android.permission.CAMERA --device emulator-5554 --json
orca emulator ax --device emulator-5554 --json
orca emulator logcat --lines 100 --device emulator-5554 --json
Next action
Run orca emulator devices --json to find a booted device, then drive it with
--device <serial> while watching the emulator window.
See also: orca-emulator (iOS, macOS-only), orca-cli (terminals, worktrees,
built-in browser), computer-use (desktop UI outside the emulator).
1---2name: orca-emulator-android3description: Control an Android emulator / device from inside Orca using the `orca` CLI. Use for listing/booting AVDs, taps, swipes, typing, hardware buttons (incl. Back and Recents), rotation, app install/launch, runtime permissions, the accessibility tree, and logcat — driving a real adb-connected device or emulator. Cross-platform (Windows, Linux, macOS). Complements the orca-emulator (iOS) and orca-cli skills.4license: Apache-2.05---67# Orca Emulator — Android (adb / emulator powered)89Drive an Android emulator or adb-connected device **from within Orca** using10`orca emulator ...` commands. The Android backend shells out to the Android SDK11(`adb`, `emulator`, `avdmanager`) that Android Studio installs, so it works on12Windows, Linux, and macOS — unlike the iOS backend (`orca-emulator`), which is13macOS-only. Device control uses `adb shell input`, so it works without any extra14streaming server.1516> **Status:** device discovery + lifecycle + full input/capability control are17> live. The embedded 60fps **visual pane** (scrcpy/H.264) is in development — for18> now, watch the device in Android Studio's emulator window while you drive it19> from the CLI.2021## When to use2223- List, boot, and target Android emulators/AVDs and physical devices.24- **Tap, swipe, type, press hardware buttons (home/back/recents/power/volume),25 rotate** a running Android device.26- **Install** an APK, **launch** an app, **grant/revoke** runtime permissions.27- Read the **accessibility tree** (`uiautomator`) or capture **logcat**.28- Run an arbitrary `adb shell` command via `exec`.2930## When NOT to use3132- iOS simulators → use the `orca-emulator` skill (macOS only).33- Building the app → use Gradle / `./gradlew assembleDebug`, then `install`.34- Camera/sensor injection → not supported yet (Android virtual-scene is out of35 scope for now).36- Remote/SSH device control → out of scope; the SDK + device are local to the host.3738## Prerequisites (surfaced by Orca)3940- **Android Studio / Android SDK** installed, with `ANDROID_HOME` (or41 `ANDROID_SDK_ROOT`) set. Orca also checks the per-OS default location42 (`%LOCALAPPDATA%\Android\Sdk`, `~/Library/Android/sdk`, `~/Android/Sdk`).43- `adb` + `emulator` on the SDK path; at least one **AVD** (create in Android44 Studio ▸ Device Manager) or a connected device with USB debugging.45- A device that is **booted and `adb`-visible** for input/capability commands46 (an AVD that is still shutdown can be listed but must be booted first).4748Orca returns a clear message when the SDK is missing49(`Android SDK not found. Install Android Studio and set ANDROID_HOME.`).5051## Mental model5253```54┌────────────────────────┐55│ orca CLI (agents) │ e.g. orca emulator tap 0.5 0.7 --device emulator-555456└───────────┬────────────┘57 │ RPC58 ▼59┌────────────────────────┐ resolves backend by device60│ EmulatorBridge (router)│ ─────────────────────────────► AndroidEmulatorBackend61└────────────────────────┘ │ adb / emulator / avdmanager62 ▼63 Android emulator / device64```6566Orca owns backend routing and the per-worktree active-device registry. The67Android backend converts Orca's normalized 0–1 coordinates to device pixels and68issues `adb shell input` events; AVD names resolve to running adb serials.6970## Common operations7172Use `--json` for agent-friendly output. Coordinates are **normalized 0..1**73(top-left origin) — never pixels; Orca converts using the live screen size.7475| Goal | Command | Notes |76|----------------------------|----------------------------------------------------------------|-------|77| List devices + AVDs | `orca emulator devices --json` | Cross-platform; shows iOS + Android with a platform column, booted vs shutdown. |78| Single tap | `orca emulator tap <x> <y> --device <serial>` | Normalized 0..1. Preferred for single taps. |79| Swipe / gesture | `orca emulator gesture '<json>' --device <serial>` | adb approximates the path by its endpoints (start→end). |80| Type text | `orca emulator type "user@example.com" --device <serial>` | US ASCII; spaces handled. No newlines. |81| Hardware button | `orca emulator button back --device <serial>` | home, back, recents, power, volume_up, volume_down. |82| Rotate | `orca emulator rotate landscape_left --device <serial>` | Sets user_rotation (disables auto-rotate). |83| Install an APK | `orca emulator install ./app-debug.apk --reinstall --device <serial>` | `--reinstall` passes `-r`. |84| Launch an app | `orca emulator launch com.acme.app --activity .MainActivity --device <serial>` | Omit `--activity` to launch the default LAUNCHER activity. |85| Grant a permission | `orca emulator permissions grant com.acme.app android.permission.CAMERA --device <serial>` | grant / revoke / reset. |86| Accessibility tree | `orca emulator ax --device <serial> --json` | `uiautomator dump` parsed to a node tree. |87| Logcat (one-shot) | `orca emulator logcat --lines 200 --device <serial>` | Dumps recent lines; parsed to entries. |88| Raw adb shell | `orca emulator exec --command "getprop ro.build.version.sdk" --device <serial>` | Runs `adb -s <serial> shell <command>`. |8990## Critical gotchas (teach agents)9192- **All coordinates are normalized 0..1** (top-left origin), never pixels — Orca93 scales to the device's live resolution.94- **Target a running device by its adb serial** (e.g. `emulator-5554`) shown in95 `orca emulator devices`. An AVD name resolves only once that AVD is booted.96- The device must be **booted and adb-visible** before input/capability commands;97 a shutdown AVD is listed with `state: shutdown` and must be started first98 (Android Studio, or `emulator @<avd>`).99- `type` uses `adb shell input text` — US ASCII, spaces are handled, newlines are100 not. For unicode-heavy input, use the app UI directly.101- `gesture` is a straight swipe between the first and last point (adb limitation);102 fine for scroll/swipe, not for true multi-touch paths.103- Capability verbs (`install/launch/permissions/ax/logcat`) are **Android-only**;104 running them against an iOS device fails with `emulator_unsupported`.105- No camera/sensor injection yet.106107## Targeting devices & worktrees108109- Explicit device: `--device <serial>` (recommended for Android today) or an AVD110 name once booted.111- `orca emulator devices` is global (lists every backend's devices); other verbs112 target the resolved device's backend automatically.113- `--worktree <selector>` scopes to a worktree's active device once the114 attach/active flow lands for Android.115116## Examples (agent-friendly)117118```sh119orca emulator devices --json120orca emulator tap 0.5 0.85 --device emulator-5554 --json121orca emulator type "hello world" --device emulator-5554 --json122orca emulator button recents --device emulator-5554 --json123orca emulator install ./app-debug.apk --reinstall --device emulator-5554 --json124orca emulator launch com.acme.app --device emulator-5554 --json125orca emulator permissions grant com.acme.app android.permission.CAMERA --device emulator-5554 --json126orca emulator ax --device emulator-5554 --json127orca emulator logcat --lines 100 --device emulator-5554 --json128```129130## Next action131132Run `orca emulator devices --json` to find a booted device, then drive it with133`--device <serial>` while watching the emulator window.134135See also: `orca-emulator` (iOS, macOS-only), `orca-cli` (terminals, worktrees,136built-in browser), `computer-use` (desktop UI outside the emulator).
peteedoo