Install and connect the phone
Move StupidMirror to Applications and open it. Connect, unlock and trust the phone; Android needs authorized ADB.
A real phone, inside your Codex chat.
StupidMirror bundles a Codex plugin. Your agent sees the live screen of a real iPhone or Android device, operates it through MCP, and you point at exactly what you mean with annotations.
Connect in four steps
No repository clone, Python or Node.js install, or token copying is needed for the installed app.
Run iPhone setup once
Both USB and Wi-Fi iPhone video need the signed screen agent prepared through Set Up This iPhone over USB. Video needs no Camera permission. System touch on iOS 27+ needs Xcode, trust and Developer Mode.
Click Connect Codex
In Settings → MCP Automation, click Connect Codex. The app enables local MCP and installs its bundled plugin through the Codex desktop app's CLI.
Ask Codex
Open a new Codex chat, select StupidMirror and ask: “Show my phone inside Codex without tapping anything.” The panel opens through show_screen.
View, operate, annotate
View
Choose a device; pause and resume, refresh, return Home or copy a screenshot. Video plays in the chat without a separate mirror window.
Operate
Enable Operate to send single-finger presses, holds and drags through the same backend as the native mirror. Hold the left mouse button for a long press; right-click does not send one. Compatibility control remains available.
Trackpad input
Native mirror scrolling, pinch and rotation stream through the system gesture service when available, with phases and scroll momentum. The browser panel can only forward fallback scroll increments from DOM wheel events. On iOS, programmatic pinch or rotate requests keep their specified center through WDA.
USB audio
Choose Phone to keep sound on the iPhone, or Mac to play it here. Mac audio needs Camera and Microphone permissions for the USB audio source; video itself needs neither.
Annotate
Freeze the frame and draw up to eight numbered boxes, then send the marked image and your note with Command-Enter. Drawing never taps the phone.
Let the agent act
The agent works in an observe → act → observe loop with local OCR, element IDs and targeted taps, and checks the result on the device.
Video stays on this Mac
Hardware H.264 travels over encrypted local WebRTC, with no cloud relay or STUN/TURN service. Screenshots your agent requests and annotations you send go to your AI client and follow its data settings. Never paste the MCP connection file into a chat.
Troubleshooting
Codex shows no StupidMirror tools
Reconnect the plugin and select it in a new Codex chat. After updating the app, click Connect Codex (Update or reinstall plugin) again.
Initialization fails with -32603
Older builds reject experimental client capabilities. Update to StupidMirror 0.3.1 or later and reconnect the plugin; restarting Codex does not fix it.
No device or no video
Unlock the phone, check the cable and trust prompt or ADB authorization, and refresh. Both USB and Wi-Fi iPhone video need the signed screen agent prepared by the setup guide; video needs no Camera permission.
Taps do nothing
Wait for control setup. Check Xcode, trust and Developer Mode for system touch, or the signed runner for compatibility control, then enable Operate again. Viewing and control are ready independently.
Annotations cannot be sent
The host has to support image messages. If the panel reports an unavailable composer, open the chat, ask Codex to call show_screen again and continue in the new panel. Your draft is kept.