Earn 14 free days when your bug report or suggestion is accepted — how it works

Windows + Android emulator setup

The Android emulator is the one full mobile path on a Windows host (iOS requires macOS — CodeLoop says so rather than failing cryptically). With this checklist in place, a full codeloop_verify builds the app with Gradle, boots an AVD, installs and launches the app, drives it with Maestro/adb, and captures screenshots + screen recording + logcat.

One command tells you what is missing: npx codeloop doctor checks every item on this page (adb/ANDROID_HOME resolution, AVD existence, Java, Maestro, ffmpeg, PowerShell) and prints the exact install command for anything absent.

1. Android Studio + SDK

Install Android Studio. It places the SDK at %LOCALAPPDATA%\Android\Sdkby default — and, importantly, it does not add platform-toolsto your shell PATH (adb works inside Android Studio’s terminal and nowhere else; this is the single most common Windows issue).

CodeLoop self-heals this: at startup the MCP server resolves the SDK via ANDROID_HOME → ANDROID_SDK_ROOT→ the default install location and appends platform-tools + emulatorto its own PATH, so adb works for CodeLoop (and for Maestro’s child processes) without any shell changes. Setting the env var is still good hygiene for your own terminal use:

# PowerShell (persistent, new shells only)
[Environment]::SetEnvironmentVariable("ANDROID_HOME", "$env:LOCALAPPDATA\Android\Sdk", "User")
[Environment]::SetEnvironmentVariable(
  "Path",
  [Environment]::GetEnvironmentVariable("Path", "User") + ";$env:LOCALAPPDATA\Android\Sdk\platform-tools",
  "User"
)
# Open a NEW PowerShell window, then:
adb version

2. Create an AVD (Android Virtual Device)

Android Studio → Device Manager → Create Device (any recent Pixel + a Google APIs system image is fine). Verify from a terminal:

emulator -list-avds
# e.g. Pixel_8_API_35

Pin it in .codeloop/config.json with e2e.android_avdif you have several. No AVD and no USB device means the journey has nothing to boot — codeloop doctorflags this case explicitly. The first-ever cold boot of a new AVD can take minutes; CodeLoop’s boot deadline is config-aware (e2e.boot_timeout_seconds).

3. Java + Maestro (the mobile drive engine)

# Maestro is a JVM CLI — install Java first
winget install -e --id EclipseAdoptium.Temurin.21.JDK

# Maestro via PowerShell
iwr get.maestro.mobile.dev/install.ps1 | iex

Maestro drives the journey from your app’s real labels. Without it, CodeLoop falls back to coordinate-based adb input driving — functional, but label-based flows are more reliable. A missing Java would otherwise surface as a cryptic mid-flow launcher error; CodeLoop preflights it and tells you directly.

4. ffmpeg (desktop video) — usually already prompted

winget install -e --id Gyan.FFmpeg   # or: choco install ffmpeg

Emulator screen recording uses adb screenrecordon the device, so ffmpeg is only needed for desktop-window capture on the Windows host. Note winget’s PATH update only reaches new shells started from Explorer — codeloop doctor finds the binary at the winget package path either way and explains the restart.

5. Wire it into the project

npx codeloop init
npx codeloop doctor   # everything green?

Useful .codeloop/config.jsonkeys for this host (all optional — see the e2e reference):

{
  "e2e": {
    "android_avd": "Pixel_8_API_35",          // pin an AVD
    "boot_timeout_seconds": 300,               // slow first cold boot
    "gradle_install_task": ":app:installDevDebug",  // flavored builds
    "android_app_id": "com.example.myapp.dev"       // computed applicationIds
  }
}

From here, a plain codeloop_verify(or “verify the app” to your agent) runs the full loop: Gradle build → AVD boot → install → launch → Maestro drive → screenshots + recording + logcat → gate. Physical Android phones over USB work too — enable USB debugging and CodeLoop pins every adb call to the device serial, with emulator-only actions (mock location, network simulation) guarded by clear directives.

What about iOS from Windows?

Not possible — Apple’s toolchain requires macOS. CodeLoop returns the “iOS requires macOS” directive instead of a cryptic failure. The full per-cell support map is in the compatibility matrix.

Next steps