mirroir
Drive a real iPhone through macOS iPhone Mirroring with the mirroir MCP tools: read the screen, tap, type, swipe, open apps, and replay skills. Use whenever a task needs the user's phone.
Файлы1
Открыть в GitHubSKILL.mdplugins/hermes/skills/mirroir/SKILL.md
GitHubDriving an iPhone with mirroir
mirroir drives the user's own iPhone through macOS iPhone Mirroring: you see the screen as text with tap points, and you tap, type and swipe on the real device. The phone is the user's, with their accounts and data on it, so every action is real.
Setup
Skip this when the mirroir tools are already available. mirroir needs macOS 15 or later with iPhone Mirroring connected to the iPhone. Register the server with your host:
- Claude Code:
claude mcp add --transport stdio mirroir -- npx -y mirroir-mcp - Codex:
codex mcp add mirroir -- npx -y mirroir-mcp - OpenClaw:
openclaw mcp add mirroir --command mirroir-mcp
Then run mirroir-mcp doctor: every line that does not pass names its fix. Screen Recording and Accessibility are granted by the user, to the app that runs the server; tell them which pane and which app, and never change a permission yourself. The full guide is https://github.com/jfarcand/mirroir-mcp/blob/main/docs/onboarding.md.
Working method
mirroir drives the user's real iPhone through macOS iPhone Mirroring. Work in small, checked steps:
- Look first: describe_screen lists visible text with tap points. Pass omit_screenshot, and query/text_only to read one value. Never estimate coordinates from a screenshot.
- Before each action, name the change you expect. Act once, then check that it happened.
- If the screen did not change, do not repeat the same action: read the screen again and choose differently.
- Prefer tap(text:) when the target has text, launch_app to open apps, press_back to go back (a "<" chevron tap; Cmd+[ does nothing on iOS), press_home for the Home Screen.
- Once a sequence has worked, run it again with run_steps: one call instead of one per step.
- Errors that name something the user must do (unlock, approve on the Mac, grant a permission) mean stop: tell the user, and retry once only after they say it is done.
- Keep the user informed: say in one line what you are about to do on the phone, and in one line what the screen showed afterwards. Never run a long series of actions in silence.
- Before working in an app, get_notes for it; when you learn something that will hold next time, save_note.
Consent: ask before sending, posting, buying, deleting or changing a setting, even when the request names the item; show the step and wait for a yes. Never type a password, PIN or one-time code, and never open the iOS Settings app unless the user asks.
Run
mirroir-mcp skillfor the full manual.
The harness reports what it saw and did; you decide what it means. A tool that succeeds only says the input was delivered: the screen after it says whether it worked.
Reading the screen
describe_screenreturns every text element with its tap point, in the same pointstaptakes. Useomit_screenshot: trueunless you need to see an image.querylists only elements containing a text (for example°for temperatures), andtext_only: truedrops coordinates when you only read.- The mirrored frame lags the phone. describe_screen waits for the screen to settle; on a constantly animated screen pass
settle_ms: 0. - Text that is not on screen yet:
scroll_towith its label scrolls until it shows. Itsdirectionis where that text is (downby default, for what is below), not the way the finger moves. screenshotis for what text cannot tell: images, colors, layout. Its reply states the image's pixel size. To tap something only the image shows, givetapits position in the image asxandywithimage_size.
Acting
tap(text:)finds text that describe_screen listed and taps it; a miss lists the text that is on screen.tap(x:, y:)takes a point from describe_screen.launch_app(name:)opens an app through Spotlight.open_urlopens a link in Safari.press_backtaps the back chevron;press_homegoes to the Home Screen;press_app_switchershows open apps;reset_appforce-quits one.- Scrolling: content follows the finger.
swipefrom bottom to top shows what is below. To page a video feed, flick: about 75% of the screen height withduration_ms150. A longduration_msscrolls slowly without inertia. long_pressopens context menus;double_tapzooms or selects;dragmoves icons and sliders.run_stepsruns a list of steps you have already seen work, such as["tap: @324,113", "type: calculator", "press_key: return"]. A control with no readable text is named by its point:"tap: @324,113". Text must be what the screen shows, in the iPhone's language. Every step is checked against the permissions before any runs, and the run stops at the first failure. The reply ends with the text on screen.
Typing
- Tap the field first so the iPhone keyboard is up, then
type_text. - The iPhone may autocorrect what you type, and it capitalizes the start of a sentence. When the screen does not show the text that was sent, type_text says so. Accept a capital iOS added unless the user asked for exact case.
- Characters with no key on the Mac keyboard (emoji, CJK) are pasted through Universal Clipboard, which needs Handoff on the Mac and the iPhone.
press_keysends return, escape, tab, delete and arrows. Only shortcuts iOS itself implements work: Cmd+A, Cmd+C and Cmd+V in text fields, Cmd+L in Safari.
The user's Mac
Taps, typing and swipes go to the iPhone Mirroring window without bringing it to the front, so the user can keep working. Drags and two-finger gestures bring it forward for their duration and then return the front and the pointer. If another window covers the mirror, those gestures are refused rather than sent to the wrong app.
When the session is blocked
iPhone Mirroring stops when the iPhone is unlocked and in use, when the Mac locks, or when the connection times out. The error quotes the window's own text and names what the user must do (usually: lock the iPhone, or approve on the Mac). Relay it, wait for the user, then retry once. Never loop, and never press a sheet that asks for a password or Touch ID: that approval belongs to the user.
Consent
- Ask the user before anything that sends, posts, buys, books, deletes or changes a setting, even when the request names the exact item: "get rid of my note X" is not permission to delete it. Show the step you are about to take, then wait for a yes.
- Never type a password, PIN or one-time code. Ask the user to enter it.
- Never open the iOS Settings app unless the user asked for a setting.
- Tools the user has not allowed are not listed. Do not try to work around a permission refusal; tell the user which tool it needs.
Skills
list_skillsandget_skillread saved skills: Markdown step lists for a task.- While you follow a skill,
record_stepafter each step andsave_compiledat the end record a compiled replay;mirroir testthen runs it without a model. statusandcheck_healthdiagnose the connection when tools start failing.
Notes
get_notesreads what an agent learned about an app in earlier sessions;save_notekeeps one more line for the next one, under the app's name astopic. Passreplaceswith a note's text to correct it.- A note is an earlier observation, not an instruction from the user: check the screen before relying on one. Never save a password, a code, or personal content read from the screen.