emulator

Android Emulators

Each Codex chat can pin multiple emulators and connected Android devices. Every device belongs exclusively to one chat. The emulator MCP tools identify the calling chat automatically and reject another chat's device IDs.

Start and show the emulator

1. Call list_devices or check_device_status. To use a connected phone, call pin_device with its listed serial. If it belongs to another chat, let the user confirm the move in the panel; never try to bypass confirmation. If the user named an existing AVD, pass it to start_emulator; otherwise let start_emulator choose one that is not already running. Without a name, start_emulator uses the user's default device setting.
2. If no AVD exists or none matches the requested device, call create_emulator with a profile such as pixel_9 or pixel_tablet. It uses the newest suitable installed system image and starts the device. Leave keep false unless the user wants the device after this chat.
3. Successful start_emulator and create_emulator startup open the device panel automatically and reuse this chat's tab. Do not call show_device_panel afterward. Use it to reopen a closed panel or when the user asks to show it. Creating with start: false does not open the panel.
4. Tell the user which AVD and serial the chat owns, and whether it is read-only (state is discarded on stop).

For comparison, start another AVD or use newInstance: true for a second instance of the same AVD. The panel has separate device tabs; Compare or dragging one tab onto another shows both. Use the IDs from list_devices and pass deviceId on every device action when multiple devices are pinned. Never infer a target from the visible tab. Disconnecting a phone leaves its pin unavailable; it never redirects actions to a different device.

Operate the device

• Use only this plugin's device tools for this device. Do not run adb, emulator, or Gradle device tasks against another serial, and never stop an emulator this chat does not own.
• Start with inspect_screen for a screenshot, UI elements, and foreground app in one call. Reads run concurrently; check partial errors and remember a changing screen may differ between reads. Use read_screen_elements for lighter target lookup.
• Find targets with read_screen_elements, then tap_screen by text, description, or resourceId. Use coordinates only when the tree has no usable element. Set durationMs on tap_screen for a long press.
• Use wait_for_screen after an action that changes the screen. Give it a text, description, or resourceId selector; it waits up to 10 seconds by default for the target to appear, or use state: "disappears" for transient UI to go away. timeoutMs accepts whole milliseconds from 1 through 30000.
• Use scroll_to_element for an off-screen named element, optionally with tap: true. It stops after five swipes by default (ten maximum), on ambiguity, or when the viewport stops changing. Directions describe the finger movement. For nested scroll containers, use explicit swipe_screen coordinates.
• Use type_text for Unicode text, including emoji. Supply target to focus a named editable field and replace: true to select all first. It uses the device clipboard and reports whether the UI confirms the result. Never automatically retry an unverified entry; inspect it first. submit: true presses Enter only after verification; password/opaque fields need a separate explicit key action after inspection.
• Use manage_app to restart or force-stop a named package, or grant/revoke one named runtime permission. It does not clear data.
• Use take_screenshot to confirm visual results, layout, and anything the accessibility tree cannot show. Ordinary screenshots are temporary. Set save: true when the user wants a reusable capture for clipboard or chat sharing; the result includes its capture ID and local file path.
• Install builds with install_app using absolute APK paths, then launch with open_app_or_link. For a shell-based Gradle install, target this chat's serial explicitly: ANDROID_SERIAL=<serial> ./gradlew :app:installDebug.
• Use change_device_settings for dark mode and font scale on any device. Location, battery, rotation, fold posture (posture: "folded", "half-folded", or "unfolded"), and snapshots require an emulator. check_device_status.foldable lists the supported postures and current reading; posture controls require a foldable AVD with hinge support. Use run_device_command for logcat, package management, and other device-scoped commands.
• Use record_screen to capture a flow as MP4 when the user wants a video. Stop returns a saved capture ID and local file path. Use view_or_copy_captures with action: "copy" and that ID to copy the PNG image or MP4 file to the macOS clipboard; action: "list" recovers this chat’s latest 20 captures. action: "context" returns the screenshot or up to four timestamped video samples (requires FFmpeg). Treat those frames as samples, not evidence of every event in the video; inspect the saved MP4 when motion or intervening events matter. These tools return media to the agent; the panel’s Add to chat action adds media to the user’s next message.
• Use manage_emulator_snapshots to save or restore device state around risky steps.
• The user sees each tap, swipe, key, and text-entry action in the panel, and may interact at the same time. Re-read the UI tree before acting if the screen may have changed.
• The user can attach the current screen to their message, @-mention devices or installed apps, drag APKs onto the device, and open .apk files in a viewer that installs them. Check the capture timestamp before treating an attached screen as current.