agemu

agentic-emulator (agemu)

[npm] [CI] [License: MIT]

A fast control layer for the Android emulator and iOS Simulator, for coding agents that build mobile apps. A screenshot takes 4-5 ms and reading the screen 2-23 ms.

[The same agent task with adb, agent-device, Argent and agemu, on Android and iOS]

The same 18-step shopping flow (sign in, search, cart, checkout) driven by four tool stacks. Montage · Android race · iOS race · method

claude mcp add agemu -- npx -y agentic-emulator@latest mcp

When an agent builds an app, writing the code is quick. Checking the result on a device is slow. Every screenshot, screen read, tap and reset goes through adb, simctl or Maestro, and each call takes from hundreds of milliseconds to several seconds. A test flow has dozens of these steps, so the agent spends most of its time waiting for the emulator instead of building.

agemu replaces that control layer and leaves the devices stock: the Android SDK's arm64 image and Xcode's Simulator runtime. Your app behaves exactly as it does on the standard emulator and Simulator. Agents use agemu through an MCP server or a CLI.

Where it helps

The build, run and check loop: the agent changes code, installs the app, looks at the screen, taps through a flow, reads the logs, resets, and goes again.

A whole test flow (the race above, 3 runs per tool, medians):

On iOS most of the flow's time belongs to the app itself, so the gap is smaller there.

Each step of the loop:

Each device uses less of your Mac, so it can run beside your IDE, builds and browser:

The standard Android emulator is the AVD as Android Studio runs it: 4 GB of guest RAM, a window and audio. agemu runs it headless with 2 GB, the host GPU and preinstalled Google apps turned off. The iOS simulator saves come from system services an app under test doesn't use, which agemu turns off. Idle figures are single sessions on a busy Mac, so treat them as rough.

Measured on an M2 Pro Mac with 16 GB, over agemu's daemon connection as the MCP server uses it. The method, sample sizes and every other measurement are in docs/ANDROID.md, docs/IOS.md and bench/final/.

What the agent gets

• One call per step. tap --text "Sign in" --wait-text Welcome --ui taps, waits for the result and returns the new screen. Fewer calls means fewer agent turns.
• Taps that land. A tap by selector waits until the element can take the touch: after a screen transition, or when an alert or sheet has just appeared. A flow doesn't fail because a tap came too early. --contains prefers an element whose whole text is the given text, and a switch is tapped on the switch, not in the middle of its row.
• Crash notice. When the app dies, the next call says so instead of waiting for a timeout.
• Logs and crash reports from memory, filtered to your app and to what happened since launch.
• Test capabilities. Deep links, permissions, location, clipboard, dark mode, push (iOS), clear data and uninstall. reset undoes them all.
• Lighter devices. agemu turns off system services an app under test doesn't use, such as widgets, Siri and preinstalled Google apps.
• Leaves your own devices alone. agemu touches only devices named agemu-*, so it runs next to your emulators, simulators and other tools.

Where it doesn't help

• Real phones and tablets. agemu drives the Android emulator and the iOS Simulator only.
• Boots, app launches and your app's own animations take as long as before. That time belongs to the OS and the app. AGEMU_ANDROID_ANIMATIONS=0 and AGEMU_IOS_ANIMATIONS=0 shorten animations if you opt in.
• A new Android device takes 7-8 minutes to prepare, once. agemu saves a clean baseline after the system has settled, so every later boot and reset is fast and quiet.
• More devices don't add up. On a 16 GB Mac, total throughput levels off at about 2.5 devices' worth.
• iOS needs an Apple Silicon Mac and relies on private Xcode APIs. Android also runs on Linux and Windows, where it is newer and less measured. See Known limitations.

agemu and other tools

agemu does one job: it makes the emulator and the Simulator fast and light for an agent's build, run and check loop. Other tools cover more ground. agemu runs next to them, because it touches only devices named agemu-*.

The agent race measures agemu against adb, agent-device and Argent on one task. mobile-mcp is not in it yet.

Install

claude mcp add agemu -- npx -y agentic-emulator@latest mcp   # Claude Codecodex mcp add agemu -- npx -y agentic-emulator@latest mcp    # Codex CLInpx -y agentic-emulator doctor                               # checks this Mac, prints fixes

Cursor (~/.cursor/mcp.json), Gemini CLI (~/.gemini/settings.json), Claude Desktop and other clients that read an mcpServers config:

{"mcpServers": {"agemu": {"command": "npx", "args": ["-y", "agentic-emulator@latest", "mcp"]}}}

agemu doctor checks each platform separately. One is enough: an iOS-only or Android-only Mac is fine.

For agents that use a shell, put agemu on PATH:

npm install -g agentic-emulator# or without Node, into ~/.local/bin (macOS, Linux):curl -fsSL https://raw.githubusercontent.com/piotr-graczyk-dev/agentic-emulator/main/install.sh | sh# or on Windows, in PowerShell:irm https://raw.githubusercontent.com/piotr-graczyk-dev/agentic-emulator/main/install.ps1 | iex

Other MCP clients, updates, uninstalling, building from source and troubleshooting: docs/INSTALL.md.

Use

agemu create --platform ios --name iphone              # -> an agemu-iphone simulatoragemu create --platform android --name pixel           # -> android:agemu-pixelagemu boot agemu-iphoneagemu install MyApp.app && agemu launch com.example.appagemu ui                                               # compact outline: [ref] role "text" id=... @(x,y wxh)agemu tap --text "Sign in" --wait-text Welcome --ui    # act, wait and observe in one callagemu type "hello"                                     # into the focused fieldagemu key back                                         # home, back, enter, delete, tab, escape, ...agemu screenshot -o shot.pngagemu logs com.example.app --since launch --level warnagemu crashes com.example.app                          # crash, ANR and system-kill reports with top framesagemu open myapp://orders/7 --wait-id order-7          # deep linkagemu permission grant com.example.app camera locationagemu appearance darkagemu profile small-phone                              # another screen sizeagemu reset                                            # back to the clean baselineagemu shutdown

Every command prints JSON, and agemu help lists them all. Coordinates are screenshot pixels on both platforms. With exactly one booted device, -d <device> can be left out. The test capabilities and what reset restores: docs/CAPABILITIES.md.

The MCP server exposes the same functions as 31 tools: devices, profiles, create, boot, shutdown, reset, park, resume, set_profile, screenshot, ui_tree, find, tap, swipe, type_text, press_key, install, launch, terminate, wait_for, open_url, permission, location, clipboard, appearance, apps, uninstall, clear_app_data, push, logs and crashes. While a new Android device prepares, boot returns state preparing at once and the agent polls devices, so no tool call outlasts a client timeout.

Profiles

Settings

Known limitations

• iOS uses private CoreSimulator, SimulatorKit and AccessibilityPlatformTranslation APIs. Any Xcode release can break them. This version was tested on Xcode 26.6 with iOS 26.5.
• The Simulator is not an iPhone. It runs apps natively on the Mac, so GPU, sensors, memory limits and performance differ from a real device.
• iOS reset is a soft reset. It removes user apps, privacy grants, the keychain, the pasteboard, appearance and location. Built-in apps' data stays. For a full wipe, use agemu shutdown and xcrun simctl erase.
• Android: one UiAutomation client per device. While agemu runs, uiautomator dump and UiAutomator-based tests can't connect.
• Android profiles other than the AVD's native one are resampled. Create the AVD with --profile <name> to make that profile pixel-exact.
• Rotation isn't handled, and iPad Split View and Slide Over are untested.
• Android on Windows is a preview. On GitHub's Windows runner the emulator boots under agemu, but the guest's services fail under nested virtualization, so the UI tree and taps are not yet verified on Windows. CI covers the unit tests, the daemon and the installers there, and runs the Android end-to-end test on Linux with KVM. Windows screenshots use the gRPC reply for now (see docs/INSTALL.md).

Documentation

• docs/INSTALL.md: every install method, MCP clients, updates, troubleshooting.
• docs/ARCHITECTURE.md: components and conventions.
• docs/ANDROID.md and docs/IOS.md: platform design, all measurements, caveats.
• docs/CAPABILITIES.md: test capabilities, the reset contract, logs and crashes.
• examples/agent-race: the recorded race and how to run it.

Contributing and license

Bug reports, measurements on other Macs and pull requests are welcome: see CONTRIBUTING.md, and SECURITY.md for vulnerabilities. Tests: make test (no device needed), make android-e2e and make ios-e2e. agemu is released under the MIT License; the code it includes from others is listed in THIRD_PARTY_NOTICES.md.