iOS Simulator for Codex++: a mirrored simulator inside the right panel

A panel tab, not a second application window

This is a tweak for Codex++ that adds an iOS Simulator tab to Codex's right panel. It mirrors a booted iOS simulator without opening Simulator.app, forwards touch and keyboard input, and lets you annotate simulator UI elements directly into Codex comments.

The choice to mirror rather than embed a window is what shapes the whole project. Simulator.app is a separate macOS application with its own window, and driving it from another application means either scripting it or screen capturing it. This does neither. It talks to the simulator's own surfaces directly and draws the result inside the panel.

The implementation detail named in the features list is headless simulator mirroring through CoreSimulator IOSurface. IOSurface is the macOS mechanism for sharing surfaces between processes, and CoreSimulator is the framework the simulator itself runs on. Combining them gives a live view of a running simulator with no window and no second application in the dock.

The features list is otherwise a clear inventory of what you can do once it is on screen. There is a native Codex right-panel tab and panel. There is tap, drag, swipe, keyboard, Home, Lock, Side Button, Siri and screenshot controls. There is a device picker for switching between installed simulators, and optional auto-boot when no simulator is running.

Using it is two steps. You use the right-panel plus menu and choose iOS Simulator, with the row appearing below the divider next to Codex's other panel tools, and you can also use the keyboard shortcut Cmd+Y.

There is a preflight check that runs the first time you open the tab, which shows a short fix hint if something is missing. That is a thoughtful touch, because the requirements for this kind of tweak are easy to get wrong on a machine that has the Command Line Tools installed but not the full Xcode.

Annotations are where the point of the tool becomes clear

The annotation mode is the feature that justifies the whole exercise, and the readme describes it as a way to point an agent at a specific part of the simulator UI.

The flow is open the simulator panel, click the annotation button, select an element, and write a comment. The tweak then sends that through Codex's native comment UI, and the comment carries a specific set of context: the element label and role, the simulator id, the element frame, the marker point, and the viewport size.

The examples make the value concrete. A comment like fix this button layout or why is this label truncated? becomes possible without describing coordinates by hand, and with the frame, the marker point and the viewport size attached, the receiving side knows exactly where on screen the comment refers to.

There is an honest limitation attached to it, and it is the kind that comes from doing accessibility work rather than screen recognition. Annotations use the simulator accessibility tree where possible, so they work best when the app under test has useful labels and identifiers. An app that exposes little accessibility information will annotate poorly, because there is nothing in the tree to anchor to.

That is a property of the target rather than a flaw in the tool, and it is worth knowing before you rely on annotations with an app you do not control.

Two helper binaries, compiled on first use

The implementation is a JavaScript tweak with small native helpers, and the file list is short enough to describe in full.

There is index.js, the main Codex++ tweak. There is helpers/sim-capture.swift, the headless frame capture helper, and helpers/sim-input.m, the touch, keyboard and hardware-button helper. There is manifest.json with the tweak metadata, and the top level also holds an assets/ directory, a scripts/ directory and a file called browser-Bn7IAO-k.js.

The fact that the capture helper is Swift and the input helper is Objective-C tells you why the tweak is described as JavaScript. The JavaScript is the part that talks to Codex, the panel and the comment UI, while the parts that need to sit close to the simulator are native and cannot be done from JavaScript. A Swift file for frame capture and an Objective-C file for input injection is a sensible split, since the input side is the part that has to talk to CoreSimulator's own APIs.

The helpers are compiled locally on first use and cached under ~/Library/Caches/co.bennett.ios-simulator/. The notes are clear about what that means in practice: nothing is fetched from the network, and long-running helper processes are stopped when the tweak stops.

The remaining notes describe the boundaries. Screen Recording permission is not required, which is notable because the obvious way to capture a simulator window on macOS is screen recording and that permission prompt is a common stumbling block. And simulator control is limited to the small set of commands the tweak needs, so this is a viewing and pointing tool rather than a scripting framework.

What the tweak does not attempt to be

A tool that mirrors a simulator inside an editor panel invites a comparison with the full simulator application, and the readme is careful to set the boundary.

Simulator control is limited to the small set of commands the tweak needs. That is a deliberate limit stated in the notes, and it matters for what you can build on it. Tapping, dragging, swiping, typing, pressing Home, Lock and the Side Button, invoking Siri and taking a screenshot is a set of controls for demonstrating and inspecting an app, not a scripting API. There is no way to write a test sequence, no way to assert on the state of the UI, and no way to drive the simulator from a script.

That distinction also explains the annotations. The annotation feature attaches a comment to an element in the simulator, and it is a communication mechanism rather than an automation one. The goal is to hand a piece of visual context to whoever or whatever is reading the comment, with the frame, the marker point and the viewport size attached so the reference is unambiguous.

The permissions story is worth one more look because it is where similar tools usually get in the way. Screen recording permission is not required, and nothing is fetched from the network. Both of those together mean the tweak does not read your screen and does not phone home, which is a meaningfully smaller surface than a general purpose capture tool.

The remaining scope limit is the simulator itself. Only the simulators installed on the machine are visible, with a device picker for switching between them, and at least one runtime has to be downloaded before any of this works. There is no remote device, no cloud simulator and no other machine's simulator in the picture.

Installation depends on full Xcode and a downloaded runtime

The install is a copy into a directory, and the requirements are the part to read first.

You install Codex++ and then place this folder in:

~/Library/Application Support/codex-plusplus/tweaks/

A tweak is loaded by dropping a directory into that location, and the folder name is what Codex++ uses to find it. There is a manifest.json alongside, which is the metadata the host reads to know what the tweak provides.

The requirements are listed as three items. You need macOS with full Xcode installed, and if your machine points at the Command Line Tools rather than the full Xcode you run the xcode-select command given in the requirements list.

You also need at least one downloaded iOS simulator runtime or device. That is the requirement that catches people out, because a machine with Xcode installed may still have no simulator runtimes downloaded, and the tweak has nothing to mirror until one exists.

The xcode-select command is given inline in the requirements list rather than as a block, and it is worth running it as written, because the default install of the Command Line Tools leaves the full Xcode unselected.

The preflight check covers this. It runs the first time you open the tab and shows a short fix hint if something is missing, so the failure mode is a message rather than a blank panel.

The licence is MIT, with a LICENSE file at the root, and the repository has one release, v1.0.0, an initial release from 2026-04-30. The last push was on 2026-05-07, so the project is early and small. The default branch is main.

The README is also the whole documentation. There is no separate site for this tweak, unlike the larger Codex++ project it extends, and the readme's own structure, with a Features section, a Notes section and a Files section, is what you have to work from.

Editorial conclusion

This tweak suits an iOS developer using Codex++ who wants to see the running simulator beside the code and to point at a specific element in a comment rather than describing coordinates. It does not suit anyone without full Xcode installed, since the whole thing depends on the simulator runtime and on helper binaries compiled locally, and it does not give you a general purpose iOS automation framework, because the readme is explicit that simulator control is limited to the small set of commands the tweak needs. Before installing, place the folder under the tweaks directory, run the xcode-select command if your machine points at the Command Line Tools, and download at least one simulator runtime.

Frequently asked questions

Official sources

1. b-nnett/codex-plusplus-ios-simulator on GitHub
2. Issues
3. License: MIT
4. README
5. Releases