Codex

VitalAIze shows Codex sessions beside Claude ones, marked with Codex's icon. Codex runs on a plan rather than per-token prices, so its cards show tokens and plan use instead of dollars.

What works without setup

The board reads the session files in ~/.codex/sessions on its own machine (change the folders with codex.dirs, see Settings). Each Codex session gets a card while it works, and stays for codex.idle_minutes (2 hours by default) after its last turn. Its sessions reach the Archive and Trends.

A collector does the same on its own machine and streams its Codex sessions to the hub, where they get cards and reach the Archive and Trends. See Connecting other machines.

A Codex card and its saved session show the last 8 characters of the session's id. Codex ids start with the time, so the first 8 are the same for sessions made close together.

Chats the Codex app copied in

The Codex app can copy in chats from another tool, such as your Claude Code sessions. Each copy becomes a Codex session file, written all at once, that nobody is running.

• No card. A copy gets no card on the Agents tab. Once someone carries the chat on in Codex, it is a session like any other and gets one.
• Not saved twice. When a copy comes from a Claude session in a folder the board (or the collector) already reads, it is not saved or sent: that session is saved from its own file, with its real tokens and cost. The board knows this from the list Codex keeps of what it copied, external_agent_session_imports.json in the Codex folder.
• Its dates are the conversation's. A copy that is saved shows when the chat happened, not when it was copied.

Needs you: one small hook

VitalAIze uses one Codex hook, for one thing: to know that Codex is waiting on you. Codex writes nothing to its session file while it waits, so there is no other way to tell. Nothing else in VitalAIze needs a hook, and this one sends nothing anywhere: it only leaves a note in ~/.codex/vitalaize on the same machine, which the board or the collector there reads.

Without it, everything else still works. Codex cards just never show Needs you.

• The script is put there for you. The board, or the collector on a machine that has no board, keeps it at ~/.codex/vitalaize/hook.sh, and puts it back if it is deleted or out of date.
• You tell Codex about it, once on each machine where Codex runs. That takes the two steps below.

1. Add these entries to ~/.codex/hooks.json, next to any hooks you already have there:

   {
     "hooks": {
       "PermissionRequest": [{"hooks": [{"type": "command", "command": "sh ~/.codex/vitalaize/hook.sh", "timeout": 5}]}],
       "PostToolUse": [{"hooks": [{"type": "command", "command": "sh ~/.codex/vitalaize/hook.sh", "timeout": 5}]}],
       "UserPromptSubmit": [{"hooks": [{"type": "command", "command": "sh ~/.codex/vitalaize/hook.sh", "timeout": 5}]}],
       "Stop": [{"hooks": [{"type": "command", "command": "sh ~/.codex/vitalaize/hook.sh", "timeout": 5}]}],
       "SubagentStop": [{"hooks": [{"type": "command", "command": "sh ~/.codex/vitalaize/hook.sh", "timeout": 5}]}],
       "Interrupt": [{"hooks": [{"type": "command", "command": "sh ~/.codex/vitalaize/hook.sh", "timeout": 5}]}],
       "SessionEnd": [{"hooks": [{"type": "command", "command": "sh ~/.codex/vitalaize/hook.sh", "timeout": 5}]}]
     }
   }

2. Open Codex, type /hooks and trust them. Codex skips a new or changed hook until you do, so do this again after you upgrade VitalAIze if Codex cards stop showing Needs you.

A Codex card then shows Needs you (and sends an alert, if alerts are on) when Codex asks to run something, or, in a session you started yourself in Codex, when a turn ends on a question, meaning the last paragraph of its reply ends in a question mark. It clears when Codex moves on or you reply.

The card names only the program Codex wants to run, never the whole command, since that can hold a password. The hook keeps only the latest thing Codex sent it for each session and each helper agent, in ~/.codex/vitalaize, and the board removes those after a week. The hook prints nothing and never reports an error, so it cannot stop Codex.

This is new and has not yet been seen working with a real Codex. See Known limits before you rely on it.

Help us check it: the payload recorder

You can record what Codex sends the hook, so we can check that Needs you reads it right.

1. Turn recording on: touch ~/.codex/vitalaize/capture-on
2. Use Codex as usual. A run where it asks for your approval is the most useful.
3. Turn recording off: rm ~/.codex/vitalaize/capture-on
4. Every call Codex made to the hook is now a line in ~/.codex/vitalaize/payloads.jsonl.

That file holds what you typed and what Codex ran, so read it first and leave out anything private. Then send it to the VitalAIze team, for example attached to an issue. Issues are public, so attach it only once you have checked it.