/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'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 or terminal UI, `threads --discover` marks threads other clients have open or running, and `run --resume <id>` joins such a thread. A prompt sent to a thread whose turn is already running is folded into that turn, and that turn stays the other client's: its approvals are answered where the user is looking, never by codex-collab. If the prompt carries overrides (`-m`, `-s`, `--approval`, `--dir`) or `--goal`, codex-collab refuses — those settings cannot apply to someone else's turn. The `codex` terminal UI declines every dynamic tool call on a thread it watches, which means a mid-turn consult to you is declined before you can answer; codex-collab delivers your answer into the running turn as an injected message. A turn you start on an idle thread is yours as usual. Without a shared server, Codex allows one writer per thread; a thread held elsewhere is refused with exit code 8 and a message listing the kinds of process that can hold it, though it cannot tell which one actually does. A thread the broker has used frees up about seven minutes (C