Control Codex from your iPhone. Remodex is a local-first open-source bridge + iOS app that keeps the Codex runtime on your Mac and lets your phone connect through a paired WebSocket relay session.
Right now, testing the full phone-to-Mac flow still depends on api.phodex.app.
Right now I'm letting people use the hosted relay for free while I test things and clean up the experience. Longer term, the open-source path is for self-hosted setups, and the App Store version is meant to cover the managed relay and ongoing maintenance.
The current TestFlight phase is free while I validate the app over the next few days. After that, the iOS app is planned to move to the App Store as a one-time paid app. That decision is mainly to help cover the cost of the VPS behind the pairing flow and the ongoing development/support needed to keep Remodex working well; final pricing will be shared separately.
I am very early in this project. Expect bugs.
I am not actively accepting contributions yet. If you still want to help, read CONTRIBUTING.md first.
Install the Remodex app from TestFlight before you run remodex up.
Once the app is installed, onboarding inside Remodex walks you through pairing and scanning the QR from inside the app.
If you scan the pairing QR with a generic camera or QR reader before installing the app, your device may treat the QR payload as plain text and open a web search instead of pairing.
┌──────────────┐ Paired session ┌───────────────┐ stdin/stdout ┌─────────────┐
│ Remodex iOS │ ◄────────────────────► │ remodex (Mac) │ ◄──────────────────────► │ codex │
│ app │ WebSocket bridge │ bridge │ JSON-RPC │ app-server │
└──────────────┘ └───────────────┘ └─────────────┘
│ │
│ AppleScript route bounce │ JSONL rollout
▼ ▼
┌─────────────┐ ┌─────────────┐
│ Codex.app │ ◄─── reads from ──────── │ ~/.codex/ │
│ (desktop) │ disk on navigate │ sessions │
└─────────────┘ └─────────────┘
- Run
remodex upon your Mac — a QR code appears in the terminal - Scan it with the Remodex iOS app to pair
- Your phone sends instructions to Codex through the bridge and receives responses in real-time
- The bridge handles git operations, desktop refresh, and session persistence locally
This is a monorepo with a local bridge, an iOS app target, and its tests:
├── phodex-bridge/ # Node.js bridge package used by `remodex`
│ ├── bin/ # CLI entrypoints
│ └── src/ # Bridge runtime, git/workspace handlers, refresh helpers
│
├── CodexMobile/ # Xcode project root
│ ├── CodexMobile/ # App source target
│ │ ├── Services/ # Connection, sync, incoming-event, git, and persistence logic
│ │ ├── Views/ # SwiftUI screens and timeline/sidebar components
│ │ ├── Models/ # RPC, thread, message, and UI models
│ │ └── Assets.xcassets/ # App icons and UI assets
│ ├── CodexMobileTests/ # Unit tests
│ ├── CodexMobileUITests/ # UI tests
│ └── BuildSupport/ # Info.plist and build-time support files
- Node.js v18+
- Codex CLI installed and in your PATH
- Codex desktop app (optional — for viewing threads on your Mac)
- Remodex iOS app via TestFlight installed on your iPhone or iPad before scanning the pairing QR
- macOS (for desktop refresh features — the core bridge works on any OS)
- Xcode 16+ (only if building the iOS app from source)
npm install -g remodexIf you only want to try Remodex, you can install it from npm and run it without cloning this repository.
remodex upOpen the Remodex app, follow the onboarding flow, then scan the QR code from inside the app and start coding.
cd phodex-bridge
npm install
npm startStarts the bridge:
- Spawns
codex app-server(or connects to an existing endpoint) - Connects the Mac bridge to the relay session endpoint
- Displays a QR code for phone pairing
- Forwards JSON-RPC messages bidirectionally
- Handles git commands from the phone
- Persists the active thread for later resumption
Reopens the last active thread in Codex.app on your Mac.
remodex resume
# => [remodex] Opened last active thread: abc-123 (phone)Tails the event log for a thread in real-time.
remodex watch
# => [14:32:01] Phone: "Fix the login bug in auth.ts"
# => [14:32:05] Codex: "I'll look at auth.ts and fix the login..."
# => [14:32:18] Task started
# => [14:33:42] Task completeAll optional. Sensible defaults are provided.
| Variable | Default | Description |
|---|---|---|
REMODEX_RELAY |
wss://api.phodex.app/relay |
Relay base URL used for QR pairing and phone/Mac session routing |
REMODEX_CODEX_ENDPOINT |
— | Connect to an existing Codex WebSocket instead of spawning a local codex app-server |
REMODEX_REFRESH_ENABLED |
true on local macOS runs |
Auto-refresh Codex.app when phone activity is detected (false disables it, external endpoints default to off) |
REMODEX_REFRESH_DEBOUNCE_MS |
1200 |
Debounce window (ms) for coalescing refresh events |
REMODEX_REFRESH_COMMAND |
— | Custom shell command to run instead of the built-in AppleScript refresh |
REMODEX_CODEX_BUNDLE_ID |
com.openai.codex |
macOS bundle ID of the Codex app |
CODEX_HOME |
~/.codex |
Codex data directory (used here for sessions/ rollout files) |
# Disable desktop refresh
REMODEX_REFRESH_ENABLED=false remodex up
# Connect to an existing Codex instance
REMODEX_CODEX_ENDPOINT=ws://localhost:8080 remodex up
# Use a custom relay endpoint (`ws://` is unencrypted)
REMODEX_RELAY=ws://localhost:9000/relay remodex up- Remodex is local-first: Codex, git operations, and workspace actions run on your Mac, while the iPhone acts as a paired remote control.
- The pairing QR contains the relay base URL and a random session ID. After a successful scan, the iPhone stores that pairing in Keychain and tries to reconnect automatically on relaunch or when the app returns to the foreground.
- The default relay is
wss://api.phodex.app/relay, so traffic is encrypted in transit with TLS. You can also point Remodex at your own relay if you prefer to keep routing fully under your control. - If you want to inspect or self-host the relay, the server code is available in
relay/. - On the iPhone, the default agent permission mode is
On-Request. Switching the app toFull accessauto-approves runtime approval prompts from the agent.
The bridge intercepts git/* JSON-RPC calls from the phone and executes them locally:
| Command | Description |
|---|---|
git/status |
Branch, tracking info, dirty state, file list, and diff |
git/commit |
Commit staged changes with an optional message |
git/push |
Push to remote |
git/pull |
Pull from remote (auto-aborts on conflict) |
git/branches |
List all branches with current/default markers |
git/checkout |
Switch branches |
git/createBranch |
Create and switch to a new branch |
git/log |
Recent commit history |
git/stash |
Stash working changes |
git/stashPop |
Pop the latest stash |
git/resetToRemote |
Hard reset to remote (requires confirmation) |
git/remoteUrl |
Get the remote URL and owner/repo |
The bridge also handles local workspace-scoped revert operations for the assistant revert flow:
| Command | Description |
|---|---|
workspace/revertPatchPreview |
Checks whether a reverse patch can be applied cleanly in the local repo |
workspace/revertPatchApply |
Applies the reverse patch locally when the preview succeeds |
Remodex works with both the Codex CLI and the Codex desktop app (Codex.app). Under the hood, the bridge spawns a codex app-server process — the same JSON-RPC interface that powers the desktop app and IDE extensions. Conversations are persisted as JSONL rollout files under ~/.codex/sessions, so threads started from your phone show up in the desktop app too.
Known limitation: The Codex desktop app does not live-reload when an external app-server process writes new data to disk. Threads created or updated from your phone won't appear in the desktop app until it remounts that route. Remodex now enables desktop refresh by default only on the normal local macOS flow, automatically bounces the Codex app route after new-phone-thread events, rollout-file growth, and always performs a final completion refresh so the last state lands on Mac too.
# Disable auto-refresh if you prefer manual desktop updates
REMODEX_REFRESH_ENABLED=false remodex upThis triggers a debounced deep-link bounce (codex://settings → codex://threads/<id>) that forces the desktop app to remount the current thread without interrupting any running tasks. While a turn is running, Remodex also watches the persisted rollout for that thread and issues occasional throttled refreshes so long responses become visible on Mac without a full app relaunch. If the local desktop path is unavailable, the bridge self-disables desktop refresh for the rest of that run instead of retrying noisily forever.
- Auto-reconnect: If the relay connection drops, the bridge reconnects with exponential backoff (1 s → 5 s max)
- Message buffering: Messages are queued while the relay is disconnected and flushed on reconnect
- Codex persistence: The Codex process stays alive across relay reconnects
- Graceful shutdown: SIGINT/SIGTERM cleanly close all connections
cd CodexMobile
open CodexMobile.xcodeprojBuild and run on a physical device or simulator with Xcode. The app uses SwiftUI and the current project target is iOS 18.6.
I'm not actively accepting contributions yet. See CONTRIBUTING.md for details.
Do I need an OpenAI API key? Not for Remodex itself. You need Codex CLI set up and working independently.
Does this work on Linux/Windows? The core bridge (relay + Codex forwarding + git) works on any OS. Desktop refresh (AppleScript) is macOS-only.
What happens if I close the terminal?
The bridge stops. Run remodex up again — your phone will reconnect when it detects the relay session.
Can I connect to a remote Codex instance?
Yes — set REMODEX_CODEX_ENDPOINT=ws://host:port to skip spawning a local codex app-server.
Why don't my phone threads show up in the Codex desktop app immediately?
The desktop app reads session data from disk (~/.codex/sessions) but doesn't live-reload when an external process writes new data. On macOS, Remodex now auto-refreshes Codex.app by default for the normal local bridge flow after new thread events, rollout growth, and turn completion. If you're using REMODEX_CODEX_ENDPOINT, desktop refresh defaults to off unless you explicitly enable it with REMODEX_REFRESH_ENABLED=true.
Can I self-host the relay server?
Yes. The default hosted relay runs on my VPS, and the relay server code is available in relay/ if you want to inspect it or run your own compatible relay. Then point Remodex at your relay with REMODEX_RELAY.
Is the default hosted relay safe for sensitive work?
For everyday use, it is a practical default: traffic is protected in transit with TLS and all Codex execution still happens on your Mac. If you want the tightest control over routing, set REMODEX_RELAY to a relay you run yourself.