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.
- 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.
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./install.shpowershell -ExecutionPolicy Bypass -File install.ps1After installation, reopen your terminal so the updated PATH takes effect, then run codex-collab health to verify.
The installer builds a self-contained bundle, deploys it to your home directory (~/.claude/skills/codex-collab/ on Linux/macOS, %USERPROFILE%\.claude\skills\codex-collab\ on Windows), and adds a binary shim to your PATH. Once installed, Claude discovers the skill automatically.
Development mode
Use --dev to symlink source files for live-reloading instead of building a bundle:
# Linux / macOS
./install.sh --dev
# Windows (may require Developer Mode or an elevated terminal for symlinks)
powershell -ExecutionPolicy Bypass -File install.ps1 -Dev# 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| 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 (default: auto — latest available) |
-r, --reasoning <level> |
low, medium, high, xhigh (default: auto — highest for model) |
-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) |
By default, codex-collab auto-selects the latest model (preferring -codex variants) and the highest reasoning effort supported by that model. No configuration needed — it stays current as new models are released.
To override defaults persistently, use codex-collab config:
# Show current config
codex-collab config
# Set a preferred model
codex-collab config model gpt-5.3-codex
# 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 --unsetAvailable keys: model, reasoning, sandbox, approval, timeout
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.
See CONTRIBUTING.md for development setup and guidelines. This project follows the Contributor Covenant code of conduct.
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.