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.

Where things get installed

The installer builds a self-contained bundle plus a binary shim. On Linux and macOS these go to ~/.claude/skills/codex-collab/ and ~/.local/bin. On Windows they go to %USERPROFILE%\.claude\skills\codex-collab\, and install.ps1 adds the shim to your PATH.