codex-notifier is a small program that the Codex CLI runs through its hooks, on macOS, Windows or Linux. Pair it with your phone and the moments Codex needs you arrive as a push: approve a command, check which files a patch touches, answer a question or send the next instruction. Nothing runs in the background, and it works in any terminal.
01Install
macOS and Linux
Windows (PowerShell)
Windows support is in beta.
Homebrew
Anyone with Node.js
Each line installs codex-notifier and then pairs it with your phone, which also adds its hooks to Codex. It adds six entries to ~/.codex/hooks.json and marks them trusted in ~/.codex/config.toml, so you never have to approve them in /hooks. Everything else in those files stays as it was, and a one-time backup sits next to them.
02Pair your phone
Once paired, every Codex session on this computer can reach your phone, however you start it. There are two ways to pair.
Scan a QR code from the terminal
Run codex-notifier or codex-notifier pair. It prints a QR code and a link: scan the code with your phone's camera, or open the link on the phone. No app yet? The link takes you to the store first. Got the app? The phone connects by itself.
Type the code from the app
Open Notifier for Codex on your phone and add a computer. The app shows a 6-digit code and the exact line to run, with the code already in it. Already installed? codex-notifier pair plus the code is enough. Otherwise every install line takes the code and installs and pairs in one go:
curl -fsSL https://notifierforcodex.com/install.sh | sh -s 482913irm https://notifierforcodex.com/install.ps1 | iex; codex-notifier pair 482913brew trust --formula touch-tap/tap/codex-notifier && brew install touch-tap/tap/codex-notifier && codex-notifier pair 482913npx @touchtap/codex-notifier pair 482913Swap 482913 for the code on your phone. Codes last 24 hours, and the app makes a fresh one when it runs out.
03What you get
With a phone paired, you get:
- Codex has finished: a push the moment a turn ends.
- Approvals: approve or reject a command or a patch from your phone. Reject with a note and Codex reads it.
- Questions: pick an answer, or type one, when Codex asks.
- A follow-up: right after Codex finishes, send the next instruction from the phone.
- A lock screen card (iPhone): the files being edited and the step of the plan Codex is on.
Typed something in the last 30 seconds? Nothing waits: the terminal asks as usual. Away from the keyboard? Codex waits for your phone, up to a limit you choose (10 minutes by default), and stops waiting the moment you touch the keyboard. Questions marked secret never leave your computer.
04Commands
codex-notifierPair this computer if it isn't yet, otherwise show its statuscodex-notifier pairShow a QR code and link to pair a phone, and wait for itcodex-notifier pair CODEPair with the 6-digit code from the appcodex-notifier doctorCheck the hooks, their trust, the pairing and the connectioncodex-notifier testSend a test notificationcodex-notifier devicesList paired phones, or revoke one with devices revoke NAMEcodex-notifier config showShow this computer's settingscodex-notifier syncFetch settings changed on the phone nowcodex-notifier setupReinstall the hooks and their trust (after moving the binary)05Settings
Most settings can be changed from the phone, too. A few worth knowing:
codex-notifier config set hold_ceiling_seconds 300How long Codex waits for your phone when you're away, in seconds (30 to 3600, default 600)codex-notifier config set quiet_hours 22:00-08:00Nothing goes to your phone during these hours; Codex asks in the terminal as usualcodex-notifier config set stop_hold_seconds 0How long you get to send a follow-up after Codex finishes (0 turns it off, default 120)codex-notifier pair sends a few anonymous setup events (paired, failed and why, how it was installed, the OS). Hooks send none. CODEX_NOTIFIER_NO_ANALYTICS=1 or DO_NOT_TRACK=1 turns them off.
06Updates
To update, run the install line again: it replaces the binary in place and your pairing stays put. With Homebrew, brew upgrade codex-notifier. With npm, npm i -g @touchtap/codex-notifier, or just keep using npx, which always fetches the latest.
07Uninstall
This removes the hooks and their trust entries from ~/.codex, revokes the pairings and deletes local state. Then delete the binary: ~/.local/bin/codex-notifier on macOS and Linux, %LOCALAPPDATA%\Programs\codex-notifier on Windows, or brew uninstall codex-notifier.
Erases this computer and its pairings from the relay server too, then uninstalls.