Remodex: control the Codex CLI on your Mac from an iPhone

The problem Remodex solves for Codex CLI users

Codex runs on the machine where it was installed. That is fine while you sit at the desk, and awkward the moment a long turn is still running and you leave the room. Remodex exists to close that gap without moving the runtime: the README describes it as a local-first bridge plus iOS app that keeps the Codex runtime on your Mac and lets your phone connect through a paired secure session. Nothing about your repository or credentials is relocated to a hosted service, which is the design decision the rest of the project follows from.

The audience is narrow and specific. You need the Codex CLI installed and authenticated on a Mac, Node.js v18 or newer, and an iPhone or iPad with a signed Remodex build. If any of those are missing, the bridge has nothing to talk to. The feature list is aimed at people who already live in Codex: steering an active run without restarting it, queueing follow-up prompts while a turn is still going, subagents via the `/subagents` command, git actions such as commit, push, pull and branch switching from the phone, and reasoning controls that adjust how much thinking Codex spends. Shared thread history means the phone and the Mac see the same conversation rather than two diverging copies.

How the bridge, relay and Codex app-server fit together

The architecture diagram in the README shows three hops. The iPhone app talks to the `remodex` bridge on the Mac over a WebSocket bridge carrying a paired session. The bridge talks to `codex app-server` over stdin/stdout using JSON-RPC. Alongside that, the bridge reads local Codex IPC live state and the JSONL rollout files that Codex writes.

The pairing flow is one-time. You run `remodex up` on the Mac, the bridge installs or starts a background service on macOS and prints a QR code, and you scan that QR from inside the Remodex app. After the first handshake the iPhone stores the Mac as a trusted device, the Mac bridge keeps its identity locally, and later launches attempt a trusted reconnect automatically. The QR stays available as a recovery path when trust changes or the relay cannot resolve the live session.

Two details in that flow matter more than they look. First, the relay is only a rendezvous mechanism in this description; the README states the iOS app source does not embed a public hosted endpoint, and that the transport layer stays inspectable for anyone running their own setup. Second, live conversation state is broadcast to Codex Desktop or VSCode when the local Codex IPC bus is available, with persisted JSONL history and an optional refresh workaround as fallbacks. That fallback ordering is worth knowing, because it means the desktop view of a thread can lag the phone when the IPC bus is not present.

Installing the remodex bridge and pairing an iPhone

The bridge ships as a global npm package. The README recommends installing with `@latest` so you pick up the newest bridge fixes, and notes that if you plan to use the macOS menu bar companion, `remodex` must be globally installed and available in your login-shell PATH.

npm install -g remodex@latest

Before starting the bridge, confirm that Codex itself is authenticated on the Mac. Remodex does not manage OpenAI credentials; it expects the local Codex CLI to be ready first.

codex login status
codex login

With Codex authenticated, start the bridge:

remodex up

On macOS this installs or starts the lightweight background bridge service and prints a QR code for first-time pairing or recovery. Open the Remodex app, follow the onboarding flow, and scan the QR from inside the app rather than from the system camera. The README warns that a generic camera or QR reader may treat the payload as plain text and open a web search instead of pairing. After the first scan the phone saves the Mac as trusted, and later launches try to reconnect on their own.

If pairing or startup fails with `Missing environment variable: CODEX_API_KEY`, the README says that error originates in your Codex CLI configuration, not in Remodex. Authenticate Codex directly and restart the bridge:

codex login
remodex restart

If you deliberately use API-key auth, configure Codex itself and keep keys out of the Remodex launchd plist and relay configuration:

printenv OPENAI_API_KEY | codex login --with-api-key
remodex restart

Updating later uses the same npm command, followed by `remodex restart` if the macOS background service is installed. The README states that restart refreshes the saved Node and CLI paths and the LaunchAgent policy used by `launchd` without replacing your pairing state.

Where Remodex is the wrong tool

The macOS-only daemon is the first hard boundary. The README states that the background daemon and trusted auto-reconnect flow are implemented for macOS, and that self-hosted relay setups still work on other operating systems but use the foreground bridge flow instead of the `launchd` service path. So a Linux or Windows host gives you pairing without the background service, which changes the experience: no daemon to keep the session alive, and no trusted reconnect path of the kind macOS gets.

There is no Android client described. The app is an iOS app, distributed on the App Store, with source under the `CodexMobile/` Xcode project. If your phone is not an iPhone or iPad, this project does not address your case.

The project's own warning is the second boundary. The README says the author is very early in this project and to expect bugs, and that contributions are not being actively accepted yet. That is a fair description of a tool that sits between three moving parts (the Codex CLI, a WebSocket transport, and a SwiftUI client) and whose failure modes include authentication errors that surface from Codex rather than Remodex. Treat it as something you run on a machine you control, not as infrastructure you depend on.

One more caveat sits in the onboarding itself. The pairing QR is a bootstrap credential. The README notes the QR remains available as a recovery path, which is convenient, but it also means the code printed by `remodex up` should be treated the way you would treat any pairing secret: scanned from inside the app, on a device you control, and not left on a shared screen.

How Remodex differs from SSH plus a terminal app

The obvious alternative is not another product in this category; it is an SSH client on the phone plus a terminal multiplexer on the Mac. That approach gives you a shell, and from that shell you can run `codex` directly. It requires no bridge, no pairing state, no relay, and no iOS build. It also gives you a raw terminal: a long turn scrolls past, steering means sending keystrokes into a TUI, and there is no structured notion of a thread, a queued follow-up prompt, or a git action button.

Remodex trades that generality for structure. The bridge speaks JSON-RPC to `codex app-server`, so the phone can present turns, reasoning controls, plan mode, subagents and git operations as first-class UI rather than escape sequences. It also persists session state on the Mac and shares thread history with Codex there, which an SSH session does not do on its own. The cost is everything listed above: a Node.js dependency, a global npm install, a macOS-specific daemon for the best reconnect behaviour, and an iOS app you either install from the App Store or build yourself in Xcode.

If your goal is simply to reach a shell on your Mac from a phone, SSH is the smaller tool and Remodex adds nothing. If your goal is to operate Codex turns, and you want the phone to understand what a turn is, the bridge is doing real work that a terminal cannot.

Maintenance, licence and upgrade cost

Remodex is licensed Apache-2.0, with the licence file at the repository root and a `Legal/` directory alongside it. Apache-2.0 permits commercial and private use and includes an explicit patent grant, and it requires that you keep the licence and notice files when you redistribute. Building the iOS app from source and signing it yourself is a normal use of the code under that licence; redistributing a modified build brings the notice obligations with it. That is a general description of the licence, not legal advice for your situation.

Upgrade cost is low on the bridge side and higher on the app side. The bridge updates through `npm install -g remodex@latest`, and if the macOS background service is installed you follow it with `remodex restart`, which the README says refreshes the saved Node and CLI paths and LaunchAgent policy without touching pairing state. The iOS app, if you built it yourself, has to be rebuilt and reinstalled through Xcode when you want new client code. If you installed from the App Store, updates arrive through the store.

The repository does not publish releases, so there is no changelog to read before upgrading. The README also gives no last push date, which means there is no basis for describing the project as actively maintained. Check the repository's commit history yourself before you decide how much of your workflow to put behind it.

Editorial conclusion

Adopt Remodex if you already run the Codex CLI on a Mac, want to steer long turns from an iPhone, and are willing to build or install a signed iOS app. Skip it if you need Android, a Windows or Linux background service, or a stable interface, since the README says the project is very early and bugs are expected. Before pairing, verify three things: `codex login status` succeeds on the Mac, the global `remodex` binary is on your login-shell PATH, and you have a signed Remodex build on the device, because a generic QR scanner will read the pairing payload as plain text.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository