Pair Codex CLI on your computer with the official ChatGPT phone app. QR pairing, conversational setup, and remote device management.
These steps install the CLI into your user account and register its plugin with Codex. You do not need to build the source, create an API key, or install the separate Codex Folders launcher.
Install Node.js 24+ with npm and Codex CLI. Sign Codex in with ChatGPT using your usual account. Check:
node --version
codex --version
Use any operating system where Codex exposes the required native managed-server remote interface. Linux with Codex 0.163.0 is the tested baseline. macOS, Windows, and other operating systems are untested; installing the package alone does not verify native compatibility.
Install the official ChatGPT app on your phone and sign in with the same account and workspace. Some accounts or organizations may restrict remote access.
For Bash/Zsh on Linux or macOS, run this in your regular terminal:
export PATH="$HOME/.local/bin:$PATH"
curl --fail --location --output codex-remote-0.2.1.tgz \
https://github.com/Cheaux/codex-remote/releases/download/v0.2.1/codex-remote-0.2.1.tgz
npm install --global --prefix "$HOME/.local" --ignore-scripts ./codex-remote-0.2.1.tgz
codex-remote install
For PowerShell on Windows (untested):
Invoke-WebRequest -Uri https://github.com/Cheaux/codex-remote/releases/download/v0.2.1/codex-remote-0.2.1.tgz -OutFile codex-remote-0.2.1.tgz
npm install --global --ignore-scripts .\codex-remote-0.2.1.tgz
codex-remote install
The Bash/Zsh installation uses your user directory; the PowerShell installation uses npm’s default global prefix. Downloading first and installing the local archive works with npm 12’s default restriction on direct URL installs. You can also download the .tgz from the release page in your browser and install that local file.
The .tgz release already includes the built CLI and hidden plugin manifests. GitHub’s automatic Source code ZIP is for development and does not include the built CLI.
The install command registers the bundled codex-remote-local marketplace and codex-remote plugin in your selected Codex home. It does not enable remote access or restart the server.
codex-remote qr
Scan the QR or open the printed link on your phone, complete setup in ChatGPT, and then check:
codex-remote status
codex-remote devices list
Requesting a pairing code enables persistent remote access if needed. Access stays enabled until you run codex-remote disable. Pairing walkthrough
Open a new Codex terminal so it loads the installed plugin. Keep existing conversations running. Ask:
Show the QR for remote session pairing.
For an already paired phone, ask “Check my remote connection” to inspect status without generating another code.
/qr and autocompleteInstall Codex Command Extensions, then run:
codex-remote terminal enable
Open a new Codex terminal and type /q to see /qr. Folders is not required. The shared host currently supports Linux/macOS with Python 3; its Windows terminal backend is not implemented. Conversational pairing and the standalone CLI do not require it.
The host owns one launcher and its command menu. Remote and Folders register independently, so disabling one feature leaves the other available. Use codex-remote terminal disable to remove only /qr.
For the Bash/Zsh installation, if codex-remote is not found in a fresh terminal, put this line in the startup file for the shell you actually use:
export PATH="$HOME/.local/bin:$PATH"
For Zsh, edit ~/.zshrc. For Bash, edit ~/.bashrc. Add the line once, save, then open a new terminal. For the Windows installation, run npm prefix --global and check that directory is on PATH, then reopen your terminal. Also make sure codex remains available on PATH. PATH troubleshooting
Copy the installation command from the latest release, then run codex-remote install again. Open a new Codex terminal to load updated tools. Installed numbered releases do not update themselves.
If you enabled /qr, first run codex-remote terminal disable to unregister it. To turn off remote access as well as remove the plugin, run:
codex-remote disable
Then remove the plugin, marketplace, and CLI:
codex plugin remove codex-remote@codex-remote-local
codex plugin marketplace remove codex-remote-local
npm uninstall --global --prefix "$HOME/.local" codex-remote
Uninstallation alone preserves native remote preferences and device pairings. Use devices revoke DEVICE_ID before uninstalling if you also want to remove a particular paired device.
For the Windows default-prefix installation, use npm uninstall --global codex-remote after the same plugin and marketplace removal commands.