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 — all without leaving your Claude session.

Why

• 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, or deny.

Prerequisites

Tested on Linux (Ubuntu 22.04) and macOS. Both must be installed and on your PATH.

• Bun >= 1.0 — runs the CLI
• Codex CLI — must support codex app-server (tested with 0.106.0; npm install -g @openai/codex)

Installation

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

The install script builds a self-contained bundle, copies it to ~/.claude/skills/codex-collab/, and symlinks the binary. Once installed, Claude discovers the skill automatically and can invoke it without explicit prompting.

For development (live-reloading source changes):

./install.sh --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

CLI Commands

Command	Description
run "prompt" [opts]	Start thread, send prompt, wait, print output
review [opts]	Code review (PR, uncommitted, commit)
jobs [--json] [--all]	List threads (--limit <n> to cap)
kill <id>	Interrupt running thread
output <id>	Full log for thread
progress <id>	Recent activity (tail of log)
models	List available models
health	Check dependencies

Thread management

Command	Description
delete <id>	Archive thread, delete local files
clean	Delete old logs and stale mappings
approve <id>	Approve a pending request
decline <id>	Decline a pending request

Options

Flag	Description
-d, --dir <path>	Working directory
-m, --model <model>	Model name
-r, --reasoning <level>	low, medium, high, xhigh (default: xhigh)
-s, --sandbox <mode>	read-only, workspace-write, danger-full-access (default: workspace-write; review always uses read-only)
--mode <mode>	Review mode: pr, uncommitted, commit, custom
--ref <hash>	Commit ref for --mode commit
--resume <id>	Resume existing thread
--approval <policy>	Approval policy: never, on-request, on-failure, untrusted (default: never)
--content-only	Suppress progress lines; with output, return only extracted content
--timeout <sec>	Turn timeout (default: 1200)
--base <branch>	Base branch for PR review (default: main)

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. codex-collab is designed as a Claude Code skill, with built-in support for code review, thread management, and real-time progress streaming.