https://github.com/Kevin7Qi/codex-collab
Collaborate with Codex from Claude Code
https://github.com/Kevin7Qi/codex-collab
claude claude-code claude-skills codex skill
Last synced: about 2 months ago
JSON representation
Collaborate with Codex from Claude Code
- Host: GitHub
- URL: https://github.com/Kevin7Qi/codex-collab
- Owner: Kevin7Qi
- License: mit
- Created: 2026-02-09T12:47:37.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-04-10T09:03:00.000Z (2 months ago)
- Last Synced: 2026-04-10T11:13:49.292Z (2 months ago)
- Topics: claude, claude-code, claude-skills, codex, skill
- Language: TypeScript
- Homepage:
- Size: 655 KB
- Stars: 80
- Watchers: 1
- Forks: 8
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
- awesome-agent-skills - Kevin7Qi/codex-collab - Collaborate with Codex from Claude Code (Sponsors ❤️ / Community Skills)
- awesome-openclaw-skills - Kevin7Qi/codex-collab - | (Other)
README
# codex-collab
[](https://github.com/Kevin7Qi/codex-collab/actions/workflows/ci.yml)
[](LICENSE)
[](https://bun.sh/)
[](https://www.typescriptlang.org/)
[English](README.md) | [中文](README.zh-CN.md)
Collaborate with [Codex](https://github.com/openai/codex) from [Claude Code](https://docs.anthropic.com/en/docs/claude-code). Run tasks, get code reviews, do parallel research, all without leaving your Claude session.
codex-collab is a [Claude Code skill](https://docs.anthropic.com/en/docs/claude-code/skills) 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.
## Installation
Requires [Bun](https://bun.sh/) >= 1.0 and [Codex CLI](https://github.com/openai/codex) (`npm install -g @openai/codex`) on your PATH. Tested on Linux (Ubuntu 22.04), macOS, and Windows 10.
```bash
git clone https://github.com/Kevin7Qi/codex-collab.git
cd codex-collab
```
### Linux / macOS
```bash
./install.sh
```
### Windows
```powershell
powershell -ExecutionPolicy Bypass -File install.ps1
```
After 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:
```bash
# 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
```bash
# 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 "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 ` to cap) |
| `kill ` | Interrupt running thread |
| `output ` | Full log for thread |
| `progress ` | Recent activity (tail of log) |
| `models` | List available models |
| `health` | Check dependencies |
Thread management
| Command | Description |
|---------|-------------|
| `delete ` | Archive thread, delete local files |
| `clean` | Delete old logs and stale mappings |
| `approve ` | Approve a pending request |
| `decline ` | Decline a pending request |
Options
| Flag | Description |
|------|-------------|
| `-d, --dir ` | Working directory |
| `-m, --model ` | Model name (default: auto — latest available) |
| `-r, --reasoning ` | low, medium, high, xhigh (default: auto — highest for model) |
| `-s, --sandbox ` | read-only, workspace-write, danger-full-access (default: workspace-write; review always uses read-only) |
| `--mode ` | Review mode: pr, uncommitted, commit, custom |
| `--ref ` | Commit ref for `--mode commit` |
| `--resume ` | Resume existing thread |
| `--approval ` | Approval policy: never, on-request, on-failure, untrusted (default: never) |
| `--content-only` | Suppress progress lines; with `output`, return only extracted content |
| `--timeout ` | Turn timeout (default: 1200) |
| `--base ` | Base branch for PR review (default: main) |
## Defaults & Configuration
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`:
```bash
# 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 --unset
```
Available 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`.
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines. This project follows the [Contributor Covenant](CODE_OF_CONDUCT.md) code of conduct.
## See also
For simpler interactions, you can also check out the official [Codex MCP server](https://developers.openai.com/codex/guides/agents-sdk). codex-collab is designed as a Claude Code skill, with built-in support for code review, thread management, and real-time progress streaming.