claude-in-mobile

name

claude-in-mobile

description

This skill is the RAW claude-in-mobile MCP/CLI driver — use it to issue individual device-automation calls: drive an iOS Simulator, tap/swipe/type on an Android device or emulator, capture or diff screenshots, inspect the UI tree, audit accessibility, fan out across multiple devices, or run guarded Play Store release operations. Triggers: "drive my emulator", "tap this element", "screenshot the simulator", "call a claude-in-mobile tool", "run an autopilot flow". Does NOT produce a structured works/doesn't-work test report — for an end-to-end APK test run with a written report, use android-app-testing (or desktop-app-testing); this skill is the low-level driver those harnesses sit on top of.

Claude in Mobile

Use this skill for claude-in-mobile MCP and native CLI workflows — the raw, call-by-call driver for mobile and desktop automation.

What It Is

claude-in-mobile is an MCP server plus a native CLI for automating Android, iOS Simulator, macOS desktop apps, Aurora OS devices, Chrome/Chromium sessions, quality checks, and app-store release operations. It exposes token-efficient meta-tools instead of many single-purpose tools.

Scope vs android-app-testing

This skill is the low-level driver: you issue individual tool calls (device list, tap, screenshot, ui tree, autopilot) and interpret the results yourself. It does not enumerate an app's features, exercise them in order, or emit a structured works/doesn't-work + UX report. When the user wants that end-to-end report for an APK, use android-app-testing (or desktop-app-testing) — those harnesses call this driver underneath. If the ask is "test my app and tell me what breaks," prefer the testing harness; if the ask is "tap that button" or "screenshot the simulator," stay here.

MCP Configuration

This Testing plugin installs the skill metadata only. Register the MCP server only when no claude-in-mobile upstream is already available through Labby or the active agent runtime.

For Codex, local stdio fallback:

codex mcp add mobile -- npx -y claude-in-mobile@latest

For Claude Code, local stdio fallback:

claude mcp add --scope user --transport stdio mobile -- npx -y claude-in-mobile@latest

Equivalent JSON config:

{
  "mcpServers": {
    "mobile": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "claude-in-mobile@latest"]
    }
  }
}

Use MCP tools for interactive agent automation. Use the native CLI for scripts, CI smoke tests, local setup, or quick manual checks. Check the current package with npm view claude-in-mobile version before pinning a version. Do not overwrite an existing project or user MCP config entry unless the user asks for that change.

Requirements

• Android: adb in PATH, plus a connected USB-debuggable device or emulator.
• iOS: macOS, Xcode, a booted iOS Simulator, and WebDriverAgent/Appium xcuitest for full UI tree inspection.
• Desktop: macOS and Accessibility permission for the automation host.
• Aurora OS: audb/audb-client, SSH enabled on the device, and Python installed on the device for tap and swipe support.
• Browser: Chrome or Chromium reachable through CDP when using browser tools.
• Store publishing: platform credentials and explicit package/artifact/track confirmation before upload, rollout, promote, halt, or submit operations.

Run claude-in-mobile doctor first when setup is uncertain. It checks common dependencies such as ADB, Android SDK paths, Xcode/simctl, Appium/WDA, JDK, audb-client, and Chrome.

Android Via Labby

When using the Labby gateway, do not conclude that claude-in-mobile is broken just because the first device list shows no Android target. The gateway may have a working claude-in-mobile server while no device is attached yet, or while host ADB is bound only to loopback.

Use this recovery sequence before giving up:

# 1. Confirm the upstream is connected.
labby gateway list | rg -i 'claude-in-mobile|mobile'

# 2. Ask claude-in-mobile what it can see through Labby.
labby gateway code exec --json --code \
  'async () => await codemode.claude_in_mobile.device({ action: "list" })'

# 3. If Android is missing or system info reports ADB connection refused to
#    172.19.0.1:5037, restart host ADB so gateway/container clients can reach it.
adb kill-server
adb -a start-server
ss -ltnp | rg ':5037'

# 4. If no Android device is attached, boot an emulator instead of stopping.
avdmanager list avd
/path/to/Android/Sdk/emulator/emulator -avd <name> \
  -no-window -no-audio -no-boot-anim -no-snapshot \
  -gpu off -camera-back none -camera-front none

# 5. Wait for the emulator, then re-check both ADB and Labby.
adb devices -l
adb -s emulator-5554 shell getprop sys.boot_completed
labby gateway code exec --json --code \
  'async () => await codemode.claude_in_mobile.device({ action: "list" })'

Important details:

• Labby-hosted claude-in-mobile may reach the host ADB daemon through a Docker bridge address such as 172.19.0.1:5037; host ADB listening on 127.0.0.1:5037 is not enough. adb -a start-server binds it for gateway access.
• If an AVD appears to exit immediately, rerun the emulator in the foreground with -verbose and headless-safe flags instead of assuming the emulator is unavailable. A successful headless launch should eventually show control console listening on port 5554, ADB on port 5555.
• After Labby sees emulator-5554, use the MCP app/system tools to install, launch, capture screenshots, and collect crash logs.

Core Tool Families

The server exposes token-efficient meta-tools: core (device, input, screen, ui, app, system, flow_batch, flow_run, flow_parallel), quality (accessibility, visual, recorder, sync, autopilot, performance), and optional modules (browser, desktop, store). See references/tooling.md for the per-action breakdown of each family.

Common Workflows

Device discovery: list connected devices, set the active target, then capture a screenshot before taking action.

Visual inspection: capture an annotated screenshot, inspect the UI tree, then tap by text, accessibility label, resource id, or screenshot index. Prefer semantic locators over raw coordinates.

Cross-platform app smoke test: launch the app on Android and iOS, wait for the first screen, assert expected text, capture screenshots, and collect logs on failure.

QA pass: run accessibility audit, capture a visual baseline or compare against one, record a short repro if useful, and take performance snapshots around the interaction under test.

Desktop app test: enable the desktop module, launch or attach to the macOS app, focus the window, resize to a stable viewport, inspect windows, then drive clicks and keyboard input.

Browser test: enable or call the browser module, open/navigate to the URL, snapshot DOM refs, click/fill by ref or selector, wait for selectors, and capture visual evidence.

Store release: confirm package name, artifact path, store, track, and rollout intent before uploading or submitting. Treat store actions as destructive.

See references/tooling.md for setup commands, platform details, and coordinate handling.

Native CLI Examples

These examples assume the native CLI binary is installed via Homebrew or a release artifact. The npm package is primarily used for MCP stdio startup.

claude-in-mobile doctor
claude-in-mobile screenshot android
claude-in-mobile tap android 540 960 --from-size 540x960
claude-in-mobile input android "hello world"
claude-in-mobile ui-dump android | grep "Login"
claude-in-mobile store upload --package com.example.app --file app.aab

Guardrails

• Verify the active target before any destructive action.
• Prefer UI text or accessibility identifiers over raw coordinates when possible.
• Raw tap/swipe coordinates are interpreted in the most recent screenshot's pixel space and may be auto-scaled. UI-tree coordinates are device coordinates. Do not mix them blindly.
• Collect screenshots and logs before changing app/device state during bug investigation.
• Treat system shell, file operations, permission changes, and store actions as privileged operations.
• Do not run store publishing, rollout, or destructive device commands without explicit package, artifact, and target confirmation.