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).

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.

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.

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.

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 (Codex 0.153.4) after the broker lets go of it — at turn end for a CLI run, when its thread peer retires (30 idle minutes) for a messaged conversation.

Run Command

The run command handles prompted tasks in one call: starts a thread, sends the prompt, waits for the turn to complete, and prints output.

# Research task
codex-collab run "what does this project do?" -s read-only --content-only

# Implementation task
codex-collab run "add input validation to the login form" --content-only

# Resume an existing thread (preserves conversation context)
codex-collab run --resume <id> "now check the error handling" --content-only

# Specify working directory (omit -d if already in the project dir)
codex-collab run "investigate the auth module" -d /path/to/project --content-only

# Long or quote-riddled prompt: pass it on stdin with `run -` (no shell-quoting hazards)
cat prompt.md | codex-collab run - --content-only

IMPORTANT — Execution rules for ALL codex-collab Bash commands:

• Always use dangerouslyDisableSandbox=true — the tool writes to ~/.codex-collab/ which is outside the sandbox allowlist.
• For run and review: also use run_in_background=true — these take minutes. After launching, tell the user it's running and end your turn. While running: do NOT poll, block, wait, or spawn an agent to monitor — you will be notified automatically when the task finishes. If other tasks complete while Codex is running, handle them normally without checking on Codex. When notified: surface the result per Context Efficiency & Result Visibility below.
• run --detach returns in seconds — run it in the foreground.
• follow on a live run blocks until that run completes, and follow --watch never exits: both are primarily the user's view for their own terminal pane — don't run --watch yourself. The one agent-facing use: follow <id> in background Bash is the completion signal for a detached run (see Detached Runs below). follow on an already-finished run is a quick foreground replay.

• next blocks until something needs a response — run it in the background; its exit is your notification (see the next section below).

• All other commands (kill, threads, progress, output, peek, peer, approve, decline, answer, questions, clean, delete, config, models, templates, skill, health, version): run in the foreground — they complete in seconds. update is also foreground, but update --yes downloads and rebuilds, so allow it a few minutes.

If the user asks about progress mid-task, use TaskOutput(block=false) to read the background output stream, or codex-collab progress <id> for just the log tail. <id> is the codex-collab thread short ID (8-char hex), not the Claude Code task ID — it appears in the first progress line ([codex] Thread a1b2c3d4 started); codex-collab threads lists them. Progress lines stream in real time:

[codex] Thread a1b2c3d4 started (gpt-5.6-sol, workspace-write)
[codex] Running: npm test
[codex] Edited: src/auth.ts (update)
[codex] Turn completed (2m 14s, 1 file changed)

Code Review

For a standard PR review, call review with NO prompt string. The default pr mode runs the built-in structured diff workflow against the default branch:

# PR-style review against default branch (default — NO prompt)
codex-collab review -d /path/to/project --content-only

# Review uncommitted changes
codex-collab review --mode uncommitted -d /path/to/project --content-only

# Review a specific commit
codex-collab review --mode commit --ref abc1234 -d /path/to/project --content-only

Passing a prompt string flips to custom mode — it sends your text as free-form instructions and bypasses the built-in diff workflow. Use this when a focused or targeted review fits better than the default diff workflow (e.g., "review this for security issues", "check the error handling only"). Default to pr mode for general PR reviews:

codex-collab review "Focus on security issues in auth" -d /path/to/project --content-only

Reviews are one-shot. Each review call runs a single review inside a transient review sub-thread and exits — you cannot continue the review itself or ask the reviewer follow-up questions. For follow-ups on findings, use run --resume <id> with the relevant review output in the prompt.

review --resume <id> is useful for running a review with context from a task thread Codex has already been working in. It forks that context into an ephemeral read-only review thread, so the original task thread is not reconfigured or mutated. review with no --resume creates an ephemeral thread that disappears after the review — use this for standalone reviews with no prior context.

Review modes: pr (default), uncommitted, commit, custom

Context Efficiency & Result Visibility

• Use --content-only when reading output — result text only, no progress lines.
• run and review print results on completion; a background task's result lands in its output file.
• Read results with Bash, not the Read tool: cat the background output file, or codex-collab output <id> --last for a finished thread (--last: latest turn only). Bash output appears in the transcript where the user sees it; Read-tool content stays in your context and never reaches them.
• Then add only synthesis — the result is already on screen, so repeat nothing: say what you verified, where you disagree, what you'd add.

Resuming Threads

When consecutive tasks relate to the same project, resume the existing thread. Codex retains the conversation history, so follow-ups like "now fix what you found" or "check the tests too" work better when Codex already has context from the previous exchange. Start a fresh thread when the task is unrelated or targets a different project.

If the user asks to continue or follow up on a prior task but you don't have the thread ID in context, follow this discovery flow:

1. codex-collab threads --discover — see top 5 recent threads (server + local). If the thread was started earlier in this session, codex-collab threads --session narrows the list to exactly those.
2. If unsure which thread is right, codex-collab peek <id> to see the last exchange of a candidate.
3. For very long threads where peek alone isn't enough, spawn a subagent with codex-collab peek <id> --limit 100 --full and ask it to summarize. This keeps the firehose out of your own context.
4. codex-collab run --resume <id> "..." to continue.

Only run --discover when a resume is actually wanted — it's a lookup performed on demand.

The --resume flag accepts both ID formats:

• --resume <short-id> — 8-char hex short ID (supports prefix matching, e.g., a1b2)
• --resume <thread-id> — Full Codex thread ID (UUID, e.g., 019d680c-7b23-7f22-ab99-6584214a2bed)

Situation	Action
Same project, new prompt	codex-collab run --resume <id> "prompt"
Same project, want review	codex-collab review --resume <id>
Different project	Start new thread
Thread stuck / errored	codex-collab kill <id> then start new

If you've lost track of the thread ID, use codex-collab threads to find active threads.

Detached Runs and Following

When to detach: default to background run — it survives your turn ending and gives you a completion notification for free. Reach for --detach in exactly two situations: (1) the turn must outlive this Claude session — background tasks are killed when the session exits or restarts, which interrupts an in-flight turn, while a detached run keeps going and its result is retrievable later with output <id> --last; (2) the user is driving from their own terminal and wants the turn independent of that shell. Don't detach routine tasks: you lose the automatic completion notification (see below for how to get it back).

run --detach hands the turn to a detached runner and returns as soon as the turn is actually running — the turn's lifetime is decoupled from the invoking shell, so nothing kills it if the shell or session goes away:

codex-collab run "large refactor task" --detach --approval auto
# [codex] Detached: thread a1b2c3d4 running (gpt-5.6-sol)
# [codex]   Follow:   codex-collab follow a1b2c3d4

follow [id] is a live view of a running thread: it replays the current run so far, then streams events (commands with exit codes, file edits, Guardian decisions, approval prompts) until the run finishes, and exits with the final status (exit 0 = completed). Without an ID it attaches to the workspace's active run (or replays the most recent one), so the user can just type codex-collab follow. On an already-finished run it replays that run and exits, so it's also a quick way to review what happened.

For a multi-turn Claude ⇄ Codex conversation, suggest the user keep codex-collab follow --watch open in a separate terminal pane — it doesn't exit between turns: each new run is picked up automatically (every run shown exactly once, in start order, even across concurrent threads; runs that finished while another was displayed appear as quick replays). It renders a purpose-built, color-coded view, costs zero model context, and stops with Ctrl-C. Scope it to one thread with follow <id> --watch when multiple threads run in parallel and the user wants a dedicated pane per thread.

Completion signal for detached runs (agent-facing): the detach parent exits when the turn starts, not when it finishes — so backgrounding run --detach gives you no completion notification. When you need one, run codex-collab follow <id> in background Bash: it exits exactly when the run reaches a terminal state (exit 0 = completed), and that exit is your notification.

Watching for questions and approvals without polling (next)

codex-collab next blocks until the first event that needs a response in the workspace — an ask-channel question (see The Ask Channel below) or a pending interactive approval — prints it in full (question body plus the answer command; no follow-up questions <id> needed), and exits. Exit codes: 0 event delivered · 10 workspace idle (nothing running, nothing pending — the self-cleaning path, so a watcher never dangles after the run ends) · 3 only with an explicit --timeout <sec>.

Arm it whenever a run can produce something answerable: any run using the ask channel (--template collab), or an approval mode that can block (on-request, on-failure, untrusted). Under --approval never with no ask template, nothing can fire — a watcher there is waste (it will exit 10 when the run ends). Under auto, Guardian handles approvals autonomously, but questions still fire.

The pattern: launch the run and next as two background Bash commands in the same breath, then keep working — next exiting is your notification. next watches one workspace — arm it with the same -d you gave the run (bare next watches the cwd workspace only, and will exit 10 without ever seeing another workspace's events):

codex-collab next -d /path/to/project   # in background Bash; its exit = something needs you
# → Question q7f3a2c1  expires in 9m
#
#    <full question text>
#
#    Answer with: codex-collab answer q7f3a2c1 "<text>" -d '/path/to/project'

Respond and re-arm in the same message: when next exits, issue the answer (or approve) and a fresh next as parallel tool calls — each event then costs exactly one wake-up plus one turn. Re-arm only after answering; next has no memory of delivered events, so re-arming while a question is still pending fires immediately with the same event. A parked next consumes zero context, and long runs can ask several times — keep the loop going until the run completes (its own exit notifies you) or next exits 10.

On-disk state backs all of this regardless of which process owns the run: the run record (workspaces/*/runs/<runId>.json) carries pendingQuestion and pendingApproval while blocked, and questions[] as the resolved audit trail.

The Ask Channel (Codex Asks, You Answer)

On long or autonomous runs, Codex can pause mid-turn to ask you a question — without betting the run on your reply. Launch the run with the built-in collab template to teach it the channel:

codex-collab run "large refactor task…" --template collab --timeout 3600

Mid-turn, Codex runs codex-collab ask "…", which waits up to 10 minutes and then resolves one of two ways, both printed into Codex's own context: your answer (steering), or a graceful no-answer notice (fail-open; the run continues, and the unanswered question lands in the run record). Questions are judgment, not permission — unlike approvals they never block the run terminally. The template declares the channel and its costs but deliberately prescribes no rules: whether and when to ask is Codex's own call.

The mailbox below is the channel Codex uses for mid-turn questions — and what everything falls back to.

Restate the channel when you resume a long collab thread. The channel instructions ride the first prompt, and long threads compact oldest-first — so include one line in your own words in the resume prompt (e.g. "the collaboration channel is still open — codex-collab ask reaches me"). Codex only needs the gist; the mechanics are rediscoverable from codex-collab --help.

A pending question surfaces in the progress stream (and follow):

[codex] QUESTION FROM CODEX (expires in 10m)
[codex]   Migrating auth to JWT next. Drop the FK constraints or dual-write?
[codex]   Answer: codex-collab answer q7f3a2c1 "<text>" -d '/path/to/project'

Triage, in order of preference:

1. Answer from your own context — you launched the run; you usually hold exactly what the question needs. Questions are interrupt-priority: Codex is burning its deadline budget while you deliberate.
2. Escalate to the user when it's a preference or product call above your mandate — relay the question, relay their answer back.
3. Decline explicitly — codex-collab answer <id> "Your call — proceed and note the decision" — rather than letting it expire silently, so the audit trail can distinguish a deliberate "proceed" from nobody having been around to answer.

Answer craft: transfer judgment, not tokens. State the choice, the reason, and the condition under which Codex should deviate or ask again — a bare "yes" steers one decision; a reasoned answer steers the next ten. Long answers: codex-collab answer <id> - reads stdin.

codex-collab questions            # list pending questions (id, age, time left)
codex-collab questions <id>       # full text of one question (list view clips long ones)
codex-collab answer <id> "text"   # answer one (prefix matching works)

Approvals

By default, Codex auto-approves all actions (--approval never). For stricter control:

# Require approval for Codex-initiated actions
codex-collab run "refactor the auth module" --approval on-request --content-only

# Guardian decides each request autonomously — approve or deny, never blocking on a human
codex-collab run "refactor the auth module" --approval auto --content-only

With --approval auto, Guardian approves or denies each request on its own — it does not escalate to the interactive flow, so auto runs never block. Its decisions appear in the progress stream (Guardian approved (low risk): …) with full payloads in the thread log; judgment calls and denials additionally surface as Guardian warning: … lines carrying the risk level, the user-authorization assessment, and the rationale. Note Guardian weighs whether the user asked for the action — explicitly user-requested commands get high authorization and are usually approved; it exists to catch the model acting beyond its mandate.

When Guardian denies an action the run keeps going (the agent works around it), and the denial is saved locally with a progress hint (Override available: codex-collab approve --guardian <review-id>). If the user decides the action was actually fine:

codex-collab approve --guardian               # list pending denials
codex-collab approve --guardian <review-id>   # override one (prefix ok)

The override records a user approval for that exact action inside the thread — nothing executes immediately; the agent retries it on the thread's next run (codex-collab run --resume <short-id> "continue"). It authorizes only that specific action, not similar ones.

Under the interactive policies (on-request, on-failure, untrusted), an approval request shows:

[codex] APPROVAL NEEDED
[codex]   Command: rm -rf node_modules
[codex]   Approve: codex-collab approve <approval-id>
[codex]   Decline: codex-collab decline <approval-id>

Respond with approve or decline:

codex-collab approve <approval-id>
codex-collab decline <approval-id>

CLI Reference

Usage examples for run, review, --detach, and follow live in their sections above; this is the remaining command surface: