⏳ This skill is pending AI review.
Scores will appear once the review pipeline completes.
codex-collab
Use when the user asks to invoke, delegate to, or collaborate with Codex on any task. Also use PROACTIVELY when an independent, non-Claude perspective from Codex would add value — second opinions on code, plans, architecture, or design decisions.
Choose how to use this skill
You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.
1. Native installer
This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.
Do not guess an installer command or replace an existing version without reviewing the diff.
2. Complete package recommended
Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.
No complete ProSkills package is published for this listing yet.3. Prompt-only
Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.
Need only the instruction file?
Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.
No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.
// RATINGS
// README
codex-collab
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 acollab.consulttool. 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);nextblocks until something needs attention. Fail-open: an unanswered question never stalls a run. - Live observability —
run --detachhands a long task to a detached runner;follow --watchis 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.
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.
Claude discovers the skill automatically, including in a session that is already running. The exception is your first skill: if ~/.claude/skills/ did not exist before, restart Claude Code once so the new directory is watched.
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
update --skip mutes notices for one release, and CODEX_COLLAB_NO_UPDATE_CHECK=1 turns the release check off entirely. The local skill-drift check is offline and stays on regardless.
If the installed SKILL.md falls out of step with the binary or your template set, codex-collab skill sync shows the pending diff and applies it once you confirm.
Both upgrade paths replace the skill bundle and the binary shim. Everything under ~/.codex-collab/ is preserved: configuration, templates, thread history, and run logs. Treat ~/.claude/skills/codex-collab/ as installer-managed, since manual edits there can be overwritten on upgrade.
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
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
CLI Commands
| Command | Description |
|---|---|
run "prompt" [opts] | Start a thread, send a prompt, wait, print the output (run - reads the prompt from stdin) |
review [opts] | Code review (PR, uncommitted, or a specific commit) |
threads [--json] [--all] | List threads (--discover scans the server and marks threads open or active on the app-server, --session limits to this session) |
follow [id] | Live view of a running thread in your own terminal pane. Without an ID it attaches to the active run; --watch keeps following each new run |
output <id> [--last] | Full log for a thread (--last: only the latest turn's output) |
kill <id> [--clear] | Stop a running thread. An active goal is paused first; --clear abandons it |
peer [up] | Show the native-messaging peer's status; peer up starts the broker (and with it the peer) |
The commands Codex uses to reach Claude (peers, send, task) are under Peer messaging.
| Command | Description |
|---|---|
ask "question" | Invoked by Codex mid-turn to ask a question and wait for the answer. --timeout <sec> sets the deadline (default 600). Fails open: on expiry it tells Codex to proceed on its own judgment and exits 0 |
answer <id> "text" | Answer a pending question (answer <id> - reads from stdin) |
questions [id] | List pending questions in this workspace; with an ID, show the full text |
next | Block until something needs attention, print it in full with how to respond, then exit |
approve <id> | Approve a pending request |
// HOW IT'S BUILT
KEY FILES