Codex Relay CLI
Codex Relay lets you follow Codex CLI sessions and answer the agent from a phone while the work stays on your computer.
- 738 ★ on the repository
- Last commit
- Apache-2.0
Extended access
Why this level
- The phone gets control of a local Codex session, including action approvals.
Install
- Works in
Manual install
npx codex-relay@latestFrom Quick Start. Launching prints a QR code and a pairing link, the mobile app installs from the App Store.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The phone gets control of a local Codex session, including action approvals.
This is third-party code. Review the repository files before installing.
What it does
Codex Relay is a mobile companion for Codex CLI. `npx codex-relay@latest` starts a local relay in the workspace and prints a QR code and a `codex-relay://pair...` link. The phone app scans the code and the pairing is approved on the computer with the `approve` command. After pairing you get the Codex output stream, prompt sending, thread continuation, replies when the agent asks, queued input and approvals, and previews of git changes, local web output and files. Push notifications are set separately for a finished turn and for an action the agent waits on.
Who it is for. Developers on Codex CLI who run long tasks and want to approve agent actions without sitting at the computer.
Good fit when
- Codex waits for approval while you stepped away.
- A long task runs on the work machine and you want to see how a turn ended.
- From a phone you need to continue a thread and look at git changes.
- A local web app preview is needed on the phone itself.
Not a fit when
- You have no iOS device, the app is distributed through the App Store.
- The network gives the phone no path to the computer.
- You need Claude Code or another agent rather than Codex.
Example request
Start the relay in this folder, show the pairing QR code and explain how to approve the phone.Limitations
Node.js 22.14 or newer, an installed and signed-in Codex CLI and a network path from phone to computer are required. For different networks the README suggests Tailscale. The project is independent and not affiliated with OpenAI. The phone steers a local Codex session through the relay, so approve only your own devices. Quick Start mentions only the App Store. The relay works while it keeps running in the terminal. Pairing is approved on the computer with the `approve` command, and without it the phone does not join the session.
How to disable. Stop the relay in the terminal and remove the app from the phone. Pairing data sits in local relay state and is cleaned separately.
FAQ
How do I pair a phone?
Start the relay, scan the QR code in the app and approve the shown code with `npx codex-relay@latest approve XXXX-XXXX`.
Can the phone share a session with a terminal?
Yes. Starting with `--shared-app-server` joins the mobile app and the terminal UI on one process.
What if the phone is on another network?
Tailscale is recommended, and Tailscale Serve for web previews.
Where does the code stay?
On the computer: code, shell, git state and the Codex session stay there, and the phone talks to your own relay.
Which notifications exist?
The app settings enable alerts separately for a finished turn and for an action the agent waits on.
Discussion
No questions or reviews yet.
Related
CLI toolsA remote for Codex and Claude Code from iPhone and iPad: follow progress, reply and approve what the agent does on your computer.
A local task board with the taskctl CLI and a skill for Codex, Claude Code, and other agents: creates issues, moves statuses, and keeps comments under a fixed w
A CLI for macOS and Linux: Codex, Claude Code and Grok sessions on your computer open on your phone via QR, end-to-end encrypted
Several desktop Codex copies side by side: each account gets its own icon, sign-in, chats and plugins with no switching.
A CLI that hands session context between coding agents: continue a Claude Code session in Codex, Cursor, OpenCode and others.
A utility that brings back Codex threads lost after a provider switch by syncing sessions and SQLite and making backups.
README in short
The relay lives in the workspace and QR pairing and push notifications are set from the app. The project principle is local-first.