CLI Remote Codex — native ChatGPT Remote for Codex CLI

English · Русский

An open-source local helper for Linux/macOS. It keeps Codex, your files, and your authentication on the computer while making ordinary interactive Codex CLI sessions available through the native Remote Control flow in the ChatGPT mobile app.

codex in a terminal ── local Unix socket ──┐
                                          ├─ Codex app-server ── files and tools
ChatGPT on the phone ── OpenAI native relay ┘

The phone and terminal use the same thread, history, and executing process. This project is not a replacement Codex client, a custom cloud relay, or a mobile app. It is a small Bash router plus a native pairing/status helper.

Status and requirements

Tested on Linux with Codex CLI 0.153.4, Python 3.13, and websocket-client 1.9.0. The installer configures Bash; automatic remapping for other shells is not implemented. Unix domain sockets are required.

Direct CLI/Linux pairing is experimental. OpenAI's public mobile setup guide still primarily documents a Desktop host on macOS/Windows.

Before installing, make sure that:

• Codex CLI is installed and logged in through the ChatGPT account you want to use;
• the ChatGPT mobile app is logged in to the same account and workspace with Remote access;
• Python 3 and websocket-client are available;
• the computer stays awake and online while you use the phone connection.

Install

From a checkout of this repository:

python3 -m pip install -r requirements.txt
python3 install.py install --dry-run
python3 install.py install
source ~/.bashrc

The installer:

• copies the codex-phone skill to ${CODEX_HOME:-$HOME/.codex}/skills/codex-phone;
• installs the ~/.local/bin/codex-phone helper;
• adds one marked codex function to ~/.bashrc;
• saves the original shell file once as a local backup.

The native codex executable and its symlink are never replaced. The helper uses the real executable from PATH, so the Bash function cannot recurse into itself. The selected Python interpreter is recorded in the launcher; if you install from a virtual environment, keep that environment available.

Use

After reloading Bash:

codex
codex "Help me understand this project"
codex -C /path/to/project
codex resume THREAD_ID
codex resume --last
codex fork THREAD_ID
codex agents

Interactive launches verify the shared server and add --remote unix://. If the server is unavailable, the helper reports an error instead of silently starting an unrelated local session.

Maintenance and non-interactive commands remain native:

codex --help
codex --version
codex update
codex login
codex exec "An automation task"

An explicit --remote is preserved as an intentional endpoint choice. To bypass the Bash function in the current shell, use:

command codex

The remapping only affects Bash sessions that loaded the managed block. Direct calls from other programs and shells are unchanged.

One-time phone pairing

Start and pair the native Remote host:

codex-phone start
codex-phone pair

In ChatGPT mobile, open Remote → I have a pairing code → Enter code manually and enter the displayed code before it expires. Pairing links the phone to this host/server, not to a single chat. A pairing code is short-lived and does not need to be saved.

The helper uses the native remoteControl/pairing/start RPC with a 90-second request deadline. This works around the short pairing wait in Codex CLI 0.153.4. If the phone is already paired to this host, do not pair again.

Diagnostics and existing sessions

codex-phone doctor

The report shows CLI/app-server versions, relay status, and the number of loaded threads. connected confirms the computer-to-relay connection; check phone visibility and a selected thread separately.

If an older standalone CLI process owns a thread, finish the current turn, exit that process normally, and resume the exact thread through the shared daemon:

codex resume THREAD_ID

Do not delete locks, copy/edit history, or repeatedly generate pairing codes. An already has an active writer error means another process still owns the thread.

Security and privacy

This repository is intended to be public and contains no credentials:

• no API keys, OAuth tokens, passwords, Telegram bot tokens, or pairing codes;
• no machine-specific usernames, paths, thread IDs, or account data;
• no .env file and no custom cloud relay;
• authentication is performed by the user's native Codex CLI;
• pairing codes are generated on demand and printed only for manual entry;
• paths are resolved from the current user's $HOME, $CODEX_HOME, and PATH.

.gitignore excludes accidental .env, logs, databases, and caches; it is not an authorization mechanism. Never publish ~/.codex, pairing codes, private diagnostic logs, or session data. Keep the native Unix socket local and do not expose an app-server listener to the public Internet.

Telegram or another custom relay would require separate secrets and server infrastructure, so it is deliberately outside the main implementation.

Uninstall

python3 install.py uninstall
unset -f codex

Only the managed Bash block is removed. The helper, skill, backup, daemon, threads, and phone pairing are preserved.

Tests

python3 -m unittest discover -s tests -t . -v

The tests use temporary files and fake processes/RPC. They do not submit model tasks or create real pairing codes.

Prior art and scope

I searched public GitHub repositories on 8 September 2026. I did not find a project matching every part of this combination: the native ChatGPT mobile app, native Remote Control, a Linux CLI host, automatic routing of ordinary interactive codex commands, and no custom relay. This is not an absolute priority claim; the ecosystem changes quickly.

Related projects and discussions include:

• OpenAI Codex discussion #9200, where jeff-an shared reproducible pairing instructions and PhilipKandyba posted a Python pairing rewrite;
• mjzcng/codex-cli-mobile-pairing, a Node.js pairing helper that is now a legacy fallback;
• heycarollan/codex-usage-status, a broader Linux/VS Code companion;
• gronxb/codex-relay, RealDyllon/codex-remote, and slopus/happy, which provide their own relay and mobile clients;
• OpenAI Codex issue #23527, a related shell shim for a Desktop SSH-host flow, not an automatic wrapper for ordinary CLI invocations.

The focused contribution here is the small Bash wrapper: it preserves the familiar codex command, routes only interactive sessions to the shared unix:// daemon, leaves maintenance commands native, and adds no custom cloud layer.

Documentation

• Contributing · Правила участия
• Security · Безопасность
• Changelog · История изменений
• Native protocol notes
• Fallback paths

Sources

• Codex CLI commands
• Remote connections
• Codex app-server

License

MIT. Codex and ChatGPT are trademarks of OpenAI; this project is not affiliated with or endorsed by OpenAI.