Mobile automation CLI for AI agents - control iOS simulators with simple commands.
npm install -g agent-mobileThat's it. Appium and drivers are bundled - no separate setup required.
- macOS with Xcode installed
- iOS Simulator booted (the tool will tell you if one isn't running)
# 1. Boot a simulator
xcrun simctl boot "iPhone 16 Pro"
open -a Simulator
# 2. Check everything is ready
agent-mobile doctor# Launch an app
agent-mobile open com.apple.Preferences
# Get interactive elements with refs
agent-mobile snapshot
# Tap an element by ref
agent-mobile tap @e1Launch an iOS app by bundle ID.
agent-mobile open <bundleId> [options]
# Options:
# -d, --device <name> Device name (default: "iPhone Simulator")
# Examples:
agent-mobile open com.apple.Preferences
agent-mobile open com.apple.calculator -d "iPhone 15 Pro"Get UI elements with refs for interaction.
agent-mobile snapshot [options]
# Options:
# -a, --all Show all elements, not just interactive
# Output example:
# @e1 button "General"
# @e2 button "Display & Brightness"
# @e3 switch "Airplane Mode" [off]Tap an element by ref or coordinates.
agent-mobile tap <target>
# Examples:
agent-mobile tap @e1 # Tap by ref
agent-mobile tap 100,200 # Tap by coordinatesFill text into an input field.
agent-mobile fill <ref> <text> [options]
# Options:
# --no-clear Do not clear existing text
# Examples:
agent-mobile fill @e1 "Hello World"
agent-mobile fill @e2 "append this" --no-clearSwipe in a direction.
agent-mobile swipe <direction> [options]
# Directions: up, down, left, right
# Options:
# --distance <percent> Swipe distance (1-100, default: 50)
# Examples:
agent-mobile swipe down
agent-mobile swipe up --distance 75Take a screenshot of the current screen.
agent-mobile screenshot [filename]
# Default filename: screenshot.png
# Examples:
agent-mobile screenshot
agent-mobile screenshot my-screen.png
agent-mobile screenshot /tmp/debug.pngClose the current Appium session.
agent-mobile closeCheck system requirements and diagnose issues.
agent-mobile doctor
# Output:
# ✓ Xcode: Xcode 16.0
# ✓ Simulator: iPhone 16 Pro (booted)
# ✓ Appium: Running on port 4723
# ✓ XCUITest Driver: InstalledCopy this section to your AI assistant (Claude, Cursor, GPT, etc.):
To automate iOS simulators, use agent-mobile. Install with:
npm install -g agent-mobileBasic workflow:
agent-mobile open com.apple.Preferences # Launch app
agent-mobile snapshot # Get elements with refs
agent-mobile tap @e1 # Tap by ref
agent-mobile fill @e2 "text" # Fill input
agent-mobile swipe down # Swipe
agent-mobile screenshot /tmp/s.png # Screenshot
agent-mobile close # End sessionPrerequisites: macOS with Xcode, iOS Simulator booted (xcrun simctl boot "iPhone 16 Pro").
Run agent-mobile doctor to check setup.
agent-mobile is designed for AI coding assistants. The refs pattern (@e1, @e2, etc.) provides stable element identifiers that AI tools can easily parse and use.
When using Claude Code in a project with agent-mobile, the .claude/skills/agent-mobile/SKILL.md file provides auto-discovery. Claude will know how to:
- Launch apps and navigate UI
- Read element refs from snapshots
- Interact with elements by ref
- Take screenshots for visual debugging
User: "Open Settings and turn on Airplane Mode"
AI runs:
1. agent-mobile open com.apple.Preferences
2. agent-mobile snapshot
→ sees: @e3 switch "Airplane Mode" [off]
3. agent-mobile tap @e3
4. agent-mobile snapshot
→ confirms: @e3 switch "Airplane Mode" [on]
Run agent-mobile doctor to diagnose issues.
No simulator booted:
xcrun simctl boot "iPhone 16 Pro"
open -a SimulatorXcode not installed: Install Xcode from the App Store and open it once to accept the license.
MIT