codex-collab

English | 中文

Collaborate with Codex from Claude Code. Run tasks, get code reviews, do parallel research, all without leaving your Claude session.

codex-collab is a Claude Code skill that drives Codex through its app server JSON-RPC protocol. It manages threads, streams structured events, handles tool-call approvals, and lets you resume conversations.

Why

• Native peer messaging — The workspace broker registers Codex as a peer in Claude Code's cross-session messaging, so Claude sessions message Codex directly (SendMessage) and Codex answers back — including asking Claude questions mid-task via a collab.consult tool. No CLI in the hot path.
• Structured communication — Talks to Codex via JSON-RPC over stdio. Every event is typed and parseable.
• Event-driven progress — Streams progress lines as Codex works, so Claude sees what's happening in real time.
• Review automation — One command to run code reviews for PRs, uncommitted changes, or specific commits in a read-only sandbox.
• Thread reuse — Resume existing threads to send follow-up prompts, build on previous responses, or steer the work in a new direction.
• Approval control — Configurable approval policies for tool calls: auto-approve, interactive, deny, or Codex's Guardian auto-reviewer (--approval auto).
• Two-way ask channel — Codex can ask a question mid-turn (ask) and keep working once the answer arrives (answer); next blocks until something needs attention. Fail-open: an unanswered question never stalls a run.
• Live observability — run --detach hands a long task to a detached runner; follow --watch is a purpose-built live view that tracks every run in a terminal pane.
• Memory isolation — Threads created by codex-collab are excluded from Codex's memory feature by default, so agent-driven sessions don't shape Codex's learned picture of how you work. Opt back in with --memory (see Options for details).

Installation

Requires Bun >= 1.0 and Codex CLI (npm install -g @openai/codex) on your PATH. Tested on Linux (Ubuntu 22.04), macOS, and Windows 10.

git clone https://github.com/Kevin7Qi/codex-collab.git
cd codex-collab

Linux / macOS

./install.sh

Windows

powershell -ExecutionPolicy Bypass -File install.ps1

After installation, run codex-collab health to verify. If the command is not found, ~/.local/bin is not on your PATH yet: reopen your terminal, add the export line the installer prints, or use the full path ~/.local/bin/codex-collab health.

[!TIP] You can hand the install to an agent. Running it outside Claude Code, for example from Codex, means the skill is ready the next time you start Claude. It will ask permission to write outside the repository.

Upgrading

An installed codex-collab can update itself — no manual git pull needed:

codex-collab update            # show the latest release and changelog, confirm, then install
codex-collab update --check    # report only, install nothing

update fetches the latest release, rebuilds it locally, and reinstalls. Nothing is installed without your confirmation: an interactive y/N prompt, or an explicit --yes when there is no terminal to ask. run, review, and health print a one-line notice when a newer release exists, but never install anything themselves.

Upgrading manually still works, and is the only way to update a dev install (install.sh --dev):

git pull
./install.sh    # Windows: powershell -ExecutionPolicy Bypass -File install.ps1
codex-collab health

# Linux / macOS
./install.sh --dev

# Windows (may require Developer Mode or an elevated terminal for symlinks)
powershell -ExecutionPolicy Bypass -File install.ps1 -Dev

Quick Start

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

# Code review
codex-collab review --content-only

# Resume a thread
codex-collab run --resume <id> "now check error handling" --content-only

# Long task: detach it, watch it live in another pane
codex-collab run "large refactor" --detach --approval auto
codex-collab follow --watch

Native Peer Messaging

On macOS/Linux with a messaging-capable Claude Code, the workspace broker registers Codex in Claude Code's session registry:

codex-collab peer up      # start the broker + peer; `peer` alone shows status

From then on, any Claude session's ListAgents shows a codex(myproject-a1b2c3) peer — message it and Codex picks up the task, replying as a peer message when done. Each conversation also appears as its own peer. A topic: first line selects one — topic: auth refactor continues the conversation named codex(auth-refactor-a1b2c3) or starts it if new, so several conversations can run in parallel and you switch between them by topic (the line is stripped before Codex sees the message). Further header lines set the conversation's model:, effort:, timeout: (seconds per turn; an overdue turn is stopped and the sender told), sandbox: and approval:. With no topic line you continue your most recent conversation, and an unnamed conversation takes its name from the message text plus the thread's short ID. Replies come from that conversation's address, and replying to it continues that conversation.

Mid-task, Codex can ask its Claude peer a question through a collab.consult tool call; the question arrives as a [consult] message, and the next reply from that session is delivered back into Codex's running turn. Consults are fail-open: unanswered questions time out and Codex proceeds on its own judgment.

Claude Code gates inbound peer messages on the sender's attested permission class. A conversation attests bypass only when it runs with sandbox: danger-full-access, otherwise prompting — so a Claude session running with bypassPermissions holds Codex's replies for review unless its crossSessionInbound setting is accept. A held reply is still readable with codex-collab output <id> --last. A CLI turn on a messaged conversation with an explicit -s changes the sandbox that conversation runs and attests from then on, since Codex keeps a per-turn override for the turns that follow.

The peer degrades cleanly: on Windows, without a session registry, or with CODEX_COLLAB_PEER=off, everything below works exactly as before (CODEX_COLLAB_PEER=on insists on the peer for one invocation, as config mode peer does persistently). The broker stays resident while any Claude session is running and retires on its usual idle timeout once the last one exits.

CLI Commands

Defaults & Configuration

By default, codex-collab auto-selects the latest model (the server's default, followed up its upgrade chain, preferring a -codex variant where one exists) and the highest reasoning effort that model supports, up to xhigh. No configuration needed — it stays current as new models are released.

The max and ultra tiers are opt-in rather than auto-selected: reach for them with -r max / -r ultra on a single run, or make one the standing default with codex-collab config reasoning.

To override defaults persistently, use codex-collab config:

# Show current config
codex-collab config

# Set a preferred model
codex-collab config model gpt-5.6-sol

# Set default reasoning effort
codex-collab config reasoning high

# Unset a key (return to auto-detection)
codex-collab config model --unset

# Unset all keys
codex-collab config --unset

Available keys: model, mode, reasoning, sandbox, approval, timeout, memory

The mode key controls how codex-collab communicates with Claude: auto (the default) uses peer messaging when the platform supports it and falls back to the CLI path otherwise, peer insists on peer messaging, and cli disables peer mechanisms entirely — no agent-registry entry, no per-conversation addresses, no consult tool — routing everything through the command line. Peer messaging requires macOS or Linux with Claude Code 2.1.224 or newer; on Windows or older versions, auto falls back to the CLI path automatically without any configuration. A broker reads the mode when it starts and keeps its peer state until it restarts, so after changing the mode run codex-collab peer up in the workspace to apply it — the broker is replaced only when no turn is running.

CLI flags always take precedence over config, and config takes precedence over auto-detection:

CLI flag  >  config file  >  auto-detected

Config is stored in ~/.codex-collab/config.json.

Contributing

See CONTRIBUTING.md for development setup and guidelines. This project follows the Contributor Covenant code of conduct.

See also

For simpler interactions, you can also check out the official Codex MCP server. OpenAI also ships an official Codex plugin for Claude Code, built around slash commands you invoke yourself. codex-collab asks less of you. Tell Claude what you want in your own words and it handles the rest, running Codex in the background and coming back with what it found.

Thanks to the LINUX DO community for the feedback and support.