Mirroir — iPhone Control via iPhone Mirroring

Use mirroir to control a real iPhone through macOS iPhone Mirroring. Screenshot, tap, swipe, type, launch apps, record video, OCR the screen, and run multi-step automation scenarios — all from the terminal. Works with any app on screen, no source code or jailbreak required.

When to Use

✅ USE this skill when:

• - User wants to interact with their iPhone (tap, swipe, type, navigate)
• Sending an iMessage, WhatsApp, or any messaging app message on the iPhone
• Adding calendar events, reminders, or notes on the iPhone
• Testing a mobile app (Expo Go, TestFlight, App Store apps)
• Taking a screenshot of the iPhone screen
• Recording a video of an iPhone interaction
• Reading what's on the iPhone screen (OCR)
• Automating a multi-step iPhone workflow (login flows, app navigation)
• Checking iPhone settings or toggling network modes
• Launching an app on the iPhone
• User says "on my phone", "on my iPhone", "on iOS"

When NOT to Use

❌ DON'T use this skill when:

• - User wants to send iMessage from macOS Messages.app → use imsg skill
• User wants to manage Apple Reminders on macOS → use apple-reminders skill
• User wants to manage Apple Notes on macOS → use apple-notes skill
• User wants to automate macOS UI → use peekaboo skill
• User wants to control a camera → use camsnap skill
• The task can be done entirely on macOS without the iPhone
• iPhone Mirroring is not connected (check with mirroir status first)

Requirements

• - macOS 15+ (Sequoia or later)
• iPhone connected via iPhone Mirroring
• Karabiner-Elements (installed automatically by the mirroir installer)
• Screen Recording and Accessibility permissions granted

Setup

After installing, run the setup to configure the helper daemon and Karabiner:

CODEBLOCK0

Approve the Karabiner DriverKit extension if prompted: System Settings > General > Login Items & Extensions — enable all toggles under Karabiner-Elements.

MCP Server Configuration

Mirroir is an MCP server. Configure it in your OpenClaw MCP settings:

CODEBLOCK1

Or if installed via Homebrew, use the binary path directly:

CODEBLOCK2

Core Workflow

The typical workflow for any iPhone task:

1. 1. Check status: mirroir status — verify iPhone Mirroring is connected
2. See the screen: mirroir describe_screen — OCR the screen to find tap targets
3. Act: tap, swipe, type, launch apps based on what's visible
4. Verify: take a screenshot or describe the screen again to confirm

Available Tools (26 total)

Screen & Vision

• - screenshot — Capture the iPhone screen as PNG
• INLINECODE10 — OCR the screen, returns text elements with exact tap coordinates plus a grid-overlaid screenshot
• INLINECODE11 — Report portrait/landscape and window dimensions
• INLINECODE12 — Connection state, window geometry, device readiness
• INLINECODE13 — Full diagnostic: mirroring, helper, Karabiner, screen capture

Input

• - tap x y — Tap at coordinates
• INLINECODE15 — Two rapid taps (zoom, text selection)
• INLINECODE16 — Hold tap for context menus (default 500ms)
• INLINECODE17 — Swipe between two points
• INLINECODE18 — Slow drag for icons, sliders
• INLINECODE19 — Type text via Karabiner virtual keyboard
• INLINECODE20 — Send special keys (return, escape, tab, arrows) with optional modifiers (command, shift, option, control)
• INLINECODE21 — Trigger shake gesture (Ctrl+Cmd+Z) for undo/dev menus

Navigation

• - launch_app "AppName" — Open app via Spotlight search
• INLINECODE23 — Open URL in Safari
• INLINECODE24 — Go to home screen
• INLINECODE25 — Open app switcher
• INLINECODE26 — Open Spotlight search
• INLINECODE27 — Scroll until a text element becomes visible via OCR
• INLINECODE28 — Force-quit app via App Switcher

Recording & Measurement

• - start_recording — Start video recording of the mirrored screen
• INLINECODE30 — Stop recording and return the .mov file path
• INLINECODE31 — Time a screen transition

Network & Scenarios

• - set_network mode — Toggle airplane/Wi-Fi/cellular via Settings
• INLINECODE33 — List available YAML automation scenarios
• INLINECODE34 — Read a scenario file

Coordinates

Coordinates are in points relative to the mirroring window's top-left corner. Always use describe_screen first to get exact tap coordinates via OCR. The grid overlay helps target unlabeled icons (back arrows, gears, stars).

Examples

Send an iMessage on iPhone

CODEBLOCK3

Test a login flow

CODEBLOCK4

Running late — check Waze ETA and notify the team on Slack

CODEBLOCK5

Record a bug reproduction

CODEBLOCK6

Scenarios (YAML Automation)

Mirroir supports YAML scenario files for multi-step automation flows. Scenarios describe intents, not coordinates — the AI reads the steps and executes them using the MCP tools above, adapting to what's actually on screen.

CODEBLOCK7

The step labels (launch, wait_for, tap, type, assert_visible, screenshot) are semantic intents — the AI interprets each one and calls the appropriate MCP tools (launch_app, describe_screen, tap, type_text, screenshot, etc.) to carry them out.

Use list_scenarios to discover available scenarios and get_scenario to load them.

Tips

• - Always call describe_screen before tapping — never guess coordinates.
• Use scroll_to "label" to find off-screen elements instead of manual swiping.
• After typing, iOS autocorrect may alter text — type carefully or disable autocorrect on the iPhone.
• Use reset_app before launch_app to ensure a fresh app state.
• For keyboard shortcuts in apps, use press_key with modifiers (e.g., press_key n [command] for new message in Mail).
• INLINECODE55 with skip_ocr: true returns only the grid screenshot, letting your vision model identify icons and images OCR can't read.

Troubleshooting

• - "iPhone Mirroring not found" → Open iPhone Mirroring.app manually, ensure your iPhone is paired
• Taps not registering → Check Karabiner DriverKit extension is approved in System Settings
• Screenshot permission denied → Grant Screen Recording permission to your terminal
• Helper not running → Run npx iphone-mirroir-mcp setup to reinstall the helper daemon