mobile-harness

Automate iOS and Android device control through MobAI's DSL over HTTP.

38|3|Updated May 3, 2026
One-click install
npx skills add https://github.com/MobAI-App/mobile-harness --skill mobile-harness-mobai-app
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: mobile-harness
Source: https://github.com/MobAI-App/mobile-harness
Command: npx skills add https://github.com/MobAI-App/mobile-harness --skill mobile-harness-mobai-app

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires httpx.

What problem does it solve? Manually driving real phones, simulators, and emulators for testing, research, or data capture is slow and error-prone. This Skill lets an AI agent directly control iOS/Android devices through MobAI's /dsl/execute API using composable Python primitives, with self-healing error context on every failure. ## Core Features & Use Cases - Device automation primitives: tap, type_text, swipe, scroll, observe, screenshot, wait_for, assert_exists, siri, execute_js, and more, each compiling to one MobAI DSL step. - Two execution modes: call primitives bare for immediate execution, or wrap flows in run(thunk) to batch a whole sequence into a single HTTP call. - Self-healing failures: StepFailed carries debug.ui_tree and debug.screenshot so the agent can recover without a second observe. - Agent-editable workspace: reusable per-app domain skills (Python + markdown knowledge maps) are auto-loaded and improved every run. - Use Case: Research App Store niches by opening the store, searching a niche, capturing top apps' metadata and screenshots, and generating a comparison report, all from one agent session. ## Quick Start Ask the agent to set up mobile-harness, run mobile-harness --doctor to verify the MobAI connection, then open iOS Settings and print the UI tree as a first demo.

Frequently Asked Questions about mobile-harness

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I automate an iOS or Android device with an LLM agent?▼

Install mobile-harness, start the MobAI desktop app, and run `mobile-harness -c` with Python primitives like open_app, tap, and observe. Each primitive compiles to one MobAI DSL step posted to the device's /dsl/execute endpoint.

How do I batch multiple mobile automation steps into one HTTP call?▼

Wrap the flow in run(thunk), for example run(lambda: (open_app(...), tap(...), observe(...))). Inside run, primitives collect into a single DSL script posted once, and MobAI's explore mode skips intermediate observes.

Does mobile-harness work with iOS simulators and Android emulators?▼

Yes, it controls real devices, simulators, and emulators through MobAI's HTTP API. One limitation: webview automation via select_web_context works on iOS physical devices only, not simulators; Android supports both.

Why does my tap predicate fail with AMBIGUOUS_MATCH?▼

AMBIGUOUS_MATCH means multiple elements match the predicate, such as text="General" on the Settings root. Disambiguate with index, type, bounds_hint, or accessibility_id, and prefer text_contains over exact text for locale resilience.

What are the limitations of coordinate-based tapping in mobile automation?▼

Raw pixel coordinates break across devices, orientations, dynamic type, and OS versions, so the harness treats them as a last resort. Use predicates against the UI tree, or OCR coordinates only when the tree is empty (React Native, Flutter, system dialogs).