Snapshot
The current layout is saved to your Mac before anything is sent.
macOS app + MCP server · iPhone & iPad · USB or Wi-Fi
Rearrange your iPhone from your Mac. By hand, or by agent.
Your real home screen (real icons, real grid, real widgets) in a window on your Mac, and the same editor handed to AI agents as ten MCP tools. Nothing is written until the exact diff is on screen. Every write is snapshotted first, then read back and verified.
Developer ID signed and notarized. Not on the Mac App Store; the reason is written down, not hidden.
One home screen. Two ways in.
SCREENSHOT: editor-main.pngmain editor window, page 1, real icons, one tile mid-drag with the insertion caret
2400×1500 (16:10) @2x
2400×1500 (16:10) @2x
What an agent actually did
From Claude Code, over USB, on an iPhone 16 Pro running iOS 27.0.
preview_layout→ok · diff: 6 lines · dock + page 11 only
apply_layout→20260901-011349.680-mcp-apply.plist · verifiedClean: true
preview_layout→ok · Smart Stack 4B5D8634-… page 1 → page 2 · 147 changes
apply_layout→20260901-011440.097-mcp-apply.plist · verifiedClean: true
Patch 1 swapped Zwift and Music in the dock. Patch 2 moved a Smart Stack by its UUID onto a full page; four apps flowed into the freed slots. Both previewed, both snapshotted, both verified clean. The worked example →
Afterwards, without having watched: Write History in the app (⌘Y) lists every write like these two, marked AGENT, with the same sentences. What the app can tell you →
01 The problem
Why this exists
With a couple of hundred apps, rearranging by thumb is a ritual: hold, wiggle, drag to the edge, wait for the page flip, miss. And Apple Configurator, Apple's own desktop editor, is broken on a current device in two ways we reproduced.
Reproduced
Folder renames don't stick.
Type a name, press Return, and it reverts to the auto-generated App Store category (“Folder”, “Finance”) as soon as the view redraws.
Reproduced
It duplicates icons.
Merge two apps into a folder and one ends up inside the folder and still on the page. ScreenWright's validator refuses that state: an app can't be in two places.
Gap
Widgets are invisible to every tool.
Not Configurator, not 3uTools or AnyTrans, not sbmanager, not MDM layout payloads. ScreenWright reads Smart Stacks and widgets at their real footprint and moves, resizes, or removes them without touching what's inside.
Gap
There's no API.
Every existing route is drag-and-drop, a push-only MDM payload on a supervised device, or a robot driving simulated touches. ScreenWright exposes read → diff → write as structured calls.
An agent reorganizing 265 apps should be a structured call, not a robot dragging icons.the engineering brief, day one
02 The safety model
The safety model is the product.
The device's acknowledgement for a home-screen write carries no information, so every write, from either face, is a five-step transaction. There is no other way to write.
Validate
Compiled against the real installed-app list and real grid. Any error refuses the write.
Dry-run
The exact diff, with nothing written: the Review sheet, or preview_layout, which also says what SpringBoard will make of it.
Write, then settle
One push, then about three seconds for SpringBoard to settle.
Verify
Read back and diffed against the prediction. “Verified clean” is the only success signal.
03 The MCP server
Sixteen tools. Three of them write.
screenwright-mcp speaks Model Context Protocol over stdio, exposes sixteen tools and nothing else, and works with the app closed. The layout grammar lives inside the tool descriptions.
list_devices→get_layout→get_installed_apps→preview_layout→apply_layoutlist_devices read
Name, model, iOS version, transport, UDID. A Wi-Fi-visible device appears twice.
get_layout read
Dock, pages, folders, widgets with UUIDs, and the device's real grid metrics.
get_installed_apps read
Every bundle ID and display name; the list app refs resolve against.
validate_layout read
Compile and validate a spec. Structured errors and warnings. No write.
preview_layout read
Validate, the diff you asked for, and what SpringBoard will make of it. No write.
apply_layout write
Snapshot → validate → write → settle ~3 s → read back → verify. Refuses on any error.
list_snapshots none
Pre-write snapshots, newest first. At least the last 20 are kept.
preview_restore_snapshot none
The restore, planned and shown, with nothing written and no snapshot taken.
restore_snapshot write
Push a snapshot back through the same verified pipeline. Omit the name for the most recent.
get_icon read
An app's real icon as a PNG image block, by bundle ID.
All device tools take an optional udid (default: the first USB device) and network: true for the Wi-Fi link. A write over Wi-Fi is flagged wireless: true.
04 Limits
What it can't do. Stated up front.
Limits of what iOS exposes to a paired computer, not features we haven't gotten to. The server states the four hard ones to agents in its own instructions.
| Capability | Status | Why |
|---|---|---|
| Wallpaper | Can't be set | No command exists. On iOS 27, even reading it breaks the service channel, so the app doesn't try. |
| Icon appearance (dark, tinted, large) | Can't be set | Not in the service. |
| Removing an app from the home screen | Not possible | SpringBoard re-inserts anything omitted. ScreenWright warns rather than pretends. |
| Creating a widget | Not possible | Existing widgets can be moved, resized, or removed, by UUID. A synthesized widget renders as a dead blank tile, so the compiler refuses to invent one. |
| Blank slots, free placement, hidden apps, Today View, App Library order | Not expressible | Not in the wire format. |
05 Questions
Before you move things around.
What do I need?
A Mac on macOS 15 or later and an iPhone or iPad paired with an ordinary “Trust This Computer” tap. No MDM, no jailbreak, no supervision. Tested on an iPhone 16 Pro on iOS 27.0; also used with an iPad. The grid is read from the device.
Do I need an AI agent?
No. The app is a complete editor on its own. The MCP server is its own executable that runs with the app closed; it ships inside ScreenWright.app, and both link the same HomeScreenKit library, so an agent gets the same planner and verified writer you do.
Can I use it over Wi-Fi?
Yes. With the cable in, turn on “Show this iPhone when on Wi-Fi” in Finder once; after that, same network, no cable. A Wi-Fi-visible device appears twice in the picker (a USB row and a Wi-Fi row) and you choose the link. Writes over Wi-Fi are flagged everywhere they appear. A locked, unplugged iPhone naps its Wi-Fi, so connecting retries for about 30 seconds and the app reconnects in place with your edits intact.
Can I go back to my previous layout?
Every write snapshots the current layout to your Mac first, per device; at least the last 20 are kept. Stage one in the app and it goes through the same Review sheet as any edit; an agent previews with preview_restore_snapshot, then uses restore_snapshot, which takes a fresh snapshot first, so rolling back is itself reversible. Last resort, on the phone: Settings › General › Transfer or Reset iPhone › Reset › Reset Home Screen Layout.
An agent rearranged my phone. What did it do?
Open Write History in the app (⌘Y, or the History button in the editor). Every write leaves a snapshot on your Mac, so the list shows each one newest first: who made it, as a badge (AGENT, APP, or CLI), when, and what changed, in the same sentences the Review sheet uses. It works with the phone unplugged and covers writes made while the app was closed. It cannot tell you whether a write verified clean, and anything you moved by hand between two writes is counted with the earlier one. Write History →
What can, and can't, it change?
Apps, pages, folders, the dock, and moving, resizing or removing existing widgets. Not: creating widgets, wallpaper, icon appearance, blank slots, or removing an app from the home screen. SpringBoard puts omitted apps back, and the validator warns rather than pretends.
Why isn't it on the Mac App Store?
Talking to an iPhone means connecting to usbmuxd's UNIX socket. The App Sandbox forbids that, and no entitlement unlocks it (researched, not assumed). So ScreenWright ships the way iMazing, AnyTrans, iExplorer and 3uTools do: Developer ID signed, notarized, Hardened Runtime on, sandbox off. How it's built →
Get ScreenWright
Version 0.1.3 for macOS 15 or later
Download ScreenWright-0.1.3.dmg16.7 MB · Developer ID signed and notarized · drag to Applications
SHA-256 157ed1878eb7764ad512fc33dc12ddb016805a22843ef057c8e9d8341c9b092f
1Open the DMG and drag ScreenWright to Applications.
2Plug in your iPhone or iPad and tap Trust This Computer.
3Pick the device. Edit. Apply, and read the report.
The MCP server
screenwright-mcp is inside the app, at ScreenWright.app/Contents/MacOS/screenwright-mcp, signed and notarized with it. Register it by absolute path; with the app in Applications:
Claude Code
claude mcp add screenwright -- /Applications/ScreenWright.app/Contents/MacOS/screenwright-mcpor, in a project's .mcp.json:
.mcp.json
{
"mcpServers": {
"screenwright": { "command": "/Applications/ScreenWright.app/Contents/MacOS/screenwright-mcp", "args": [] }
}
}If the app lives somewhere else, don't guess the path: in ScreenWright, choose Help, then Set Up MCP Server, and copy either form. It reads the path of the copy that is running.
Smoke test it by hand:
shell
printf '%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}' \
'{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_devices","arguments":{}}}' \
| /Applications/ScreenWright.app/Contents/MacOS/screenwright-mcpMade by Grizzly Mining Company LLC.