AIRPOCKET GITHUB
G3GUIDE · CODEX

Codex on your iPhone

Airpocket puts the Codex sessions running in terminals on your Macs on your iPhone: what each one is doing, step by step, and which ones are waiting for you. From the phone you can reply, pick from Codex's menus, change the model and stop a turn. It works much as it does for Claude Code, with two differences worth knowing before you start.

01
FROM THE PHONE

What you can do from the phone

  • See which session needs you, in the same list as your Claude Code sessions, from every paired Mac.
  • Follow a turn while it runs. The phone reads the session file Codex writes as it goes, so each step shows up during the turn, not only after it.
  • Reply from the message box, photos included.
  • Answer a prompt. When Codex asks for permission, the phone says which tool it wants to use, and its numbered choices become buttons.
  • Change model and permissions through Codex's own /model and /permissions pickers, which open below the conversation for you to choose from. Turn fast mode and plan mode on or off.
  • Stop a turn: Stop presses Esc in its terminal, after asking you first.
  • Session commands: compact, status, usage, diff, review, resume and a new chat, and a keypad for single keys.
  • Open what it made: files the session wrote or linked, as text, code, Markdown or images.
02
DIFFERENCE ONE

Codex reads its hooks when it starts

Like Claude Code, Codex tells Airpocket what happens through hooks. airpocket setup adds them to ~/.codex/hooks.json, or under $CODEX_HOME, merged in after a timestamped backup. For Codex there are two more: one when it asks for a permission, and one when you interrupt a turn.

The difference: Codex reads that file once, when it starts. A Codex that was already running before setup never hears of the hooks. Quit it and start it again, and it appears; codex resume --last brings the conversation back.

Until then the phone says how many Codex agents run on that Mac that haven't checked in, and that they need restarting. Setup prints the same when it finishes.

A NEW SESSION NEEDS A FIRST MESSAGE

Codex starts a session only with its first prompt. A Codex you have opened and sent nothing yet, isn't on the phone. Send it a first message and it is.

03
DIFFERENCE TWO

Codex asks you to trust new hooks

Codex doesn't run a hook until you have said you trust it. The next time you start Codex after setup, it says that hooks need review before they can run. Trust Airpocket's there, or open /hooks and review them. Codex keeps your answer in its own config.

Until you do, those hooks don't run and that Codex stays off the phone. The phone shows one line saying Codex's hooks aren't trusted yet, and setup prints it too.

Codex remembers which hooks you trusted by their position in the file. That is why setup adds Airpocket's after any you already have, never in between, where it would move yours.

IN SUPERSET

Superset's codex command starts Codex with the trust check bypassed, so inside Superset the hooks run without the review, and the "not trusted yet" line is about Codex started anywhere else.

04
WHERE IT RUNS

In the terminal you already use

The same as for Claude Code. Any terminal works; start Codex through Airpocket and the phone can answer it:

$ airpocket run codex
# anything after the name goes to codex
$ airpocket run codex resume --last

Setup can alias codex to that, so you type what you typed before, and a Codex in tmux or Superset needs no change. Answering from any terminal explains what run does, and what the phone shows for a Codex started the plain way.

05
LIMITS

What it can't do, and what isn't tested yet

  • Not yet run end to end with real replies. Codex support is tested against recorded session files and against a real Codex's hooks: installed, trusted and firing. A Codex giving real model replies, driven from the phone, has not been run end to end yet.
  • A different CODEX_HOME means no hooks. A Codex started with CODEX_HOME pointing elsewhere doesn't read the hooks setup put in ~/.codex. Superset's codex command may do this, and setup doesn't detect it yet.
  • Controls wait their turn. Commands are refused while a turn runs, while a menu is open, or while unsent text sits in the prompt box.
  • Settings changed between turns can show late. Codex writes a new model, effort or fast mode into its session file only as the next turn starts. The phone reads them from the terminal's status line in the meantime, which it can't do for a read-only session.
  • No tool output and no file browser. One short line per step, and only files the session wrote, edited or linked, inside its own folder.
KNOW THIS BEFORE YOU PAIR

A paired phone can type anything into your agents, shell commands included: in Codex, as in Claude Code, a message that starts with ! runs as one, and the phone asks before sending it. A phone's token works until you revoke it on that Mac with airpocket revoke. Pair only phones you control.