/codex-collab

name: codex-collab
description: Use when the user asks to invoke, delegate to, or collaborate with Codex on any task. Also use PROACTIVELY when an independent, non-Claude perspective from Codex would add value — second opinions on code, plans, architecture, or design decisions.

codex-collab

codex-collab is a bridge between Claude and Codex. It communicates with Codex via the `codex app-server` JSON-RPC protocol, giving you structured, event-driven access to Codex's capabilities — prompting, code review, tool use, and file editing. Requires bun and the codex CLI on PATH (`codex-collab health` to verify).

<!-- MODE:peer -->

Choosing a path

`codex-collab peer up` (foreground, seconds, idempotent) prints the workspace's address, `codex(myproject-a1b2c3)`; `ListAgents` shows it plus one entry per ongoing conversation. `SendMessage` to any of them is the normal way to talk to Codex. Use the CLI instead for `review`, for a result you need within the current turn (`run` blocks and exits with a status code), and for `--goal`, `--template`, or interactive approval policies. Both paths produce the same threads: a CLI-started thread can be messaged afterwards, and a messaged conversation appears in `codex-collab threads`. <!-- /MODE:peer -->

<!-- MODE:cli -->

Choosing a path

Drive Codex interactions through the `codex-collab` CLI — `run` for tasks, `review` for code review, `--resume` for follow-ups. The ask channel is how Codex reaches you mid-task; `next` watches for those events. <!-- /MODE:cli -->

<!-- MODE:peer -->

Native Peer Messaging

`SendMessage` to `codex(myproject-a1b2c3)` starts or continues a conversation. Any message may open with a header block of `key: value` lines, stripped before Codex sees the text. `topic:` names or selects the conversation (a later `topic:` switches to that conversation, or starts it); `model:`, `effort:` and `timeout:` (seconds per turn; default 3600 or `config timeout`) set the conversation's settings and, on a later message, change them from the next turn; `sandbox:` and `approval:` are fixed when the conversation starts (`approval:` accepts only `auto`, Codex Guardian — interactive approval prompts route to CLI clients and cannot work over messaging). Parsing stops at the first line that is not a recognized key, so ordinary prose is never consumed as a header.

topic: auth refactor
effort: xhigh
sandbox: read-only

Review the login flow and tell me what you would change.

Each conversation appears as its own entry in `ListAgents` under its name. Reply to a message's `from` address to continue that specific conversation; a message to a busy conversation is delivered into the running turn and answered when it ends. Messaging is asynchronous: after sending, end your turn — do not poll, sleep, or block waiting for a reply. The reply arrives on its own as a cross-session message that wakes your session, even if you are busy with other work when it lands. A reply that lands mid-turn is folded into your context and renders in the Claude Code terminal, but not on remote views of the session (phone, web). Relaying its substance is normally enough; `codex-collab output <id> --last` is only needed when the transcript itself must carry the verbatim text — for a remote reader, or a reply held back by the receiver's `crossSessionInbound` setting.

Messaged conversations write the same run records as CLI runs, so `codex-collab progress <id>`, `output`, `follow` and `kill` work on them; the `<id>` is the short ID in the conversation's address (`peer-<id>.sock`), and `codex-collab threads` lists them alongside CLI runs. A turn that exceeds its limit is stopped and reported as a timeout, so silence means Codex is still working — use `progress` to see what it is doing, not to wait. Codex may send a `[consult]` message mid-task when it needs your judgment; reply to that address to answer. If you don't, Codex proceeds on its own after a timeout.

If `peer up` reports messaging unavailable (Windows, or an older Claude Code), the CLI handles everything. <!-- /MODE:peer -->

Codex can also reach you directly: `codex-collab send` from a Codex session delivers a message to your session from a transient peer of its own, `codex(<thread>-<hash>-<task>)`, one per message; the message's last line names the Codex thread. Reply with `SendMessage` to that address. The reply is kept for the Codex session however long the work takes, until the task expires four hours after it was sent, so the message carries no deadline. In a session codex-collab started, time spent at a prompt the user answers through Remote Control does not count toward those hours, and once they answer one there are at least 60 minutes (`config linger`) left to reply. If `send` found no Claude session in the workspace, it resumed the background one it had last stopped, conversation intact, or else started one — a `claude(<workspace>-<hash>)` session in the working directory with none of the user's conversation, running in `auto` permission mode so it can carry out the work Codex hands it, that stops after 60 idle minutes by default (`config linger`).

Codex's Own App-Server

When Codex runs a shared app-server (`codex app-server daemon start`, bound at `~/.codex/app-server-control/app-server-control.sock`), the workspace broker attaches to it instead of spawning a private one. `config server` controls this: `auto` (default) attaches when the socket answers and falls back to a private server otherwise; `shared` insists on the shared server and fails without one; `private` never attaches. The environment variable `CODEX_COLLAB_SERVER` overrides the setting for one invocation; `CODEX_COLLAB_SERVER_SOCKET` overrides the control-socket path. The setting is read when a broker starts; `codex-collab peer up` restarts the workspace broker so a change applies. `health` prints which server the broker is on.

Everything on a shared server is one space: turns you start render live in the Codex app o