⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

v0.3.2

codex-collab

kevin7qi@kevin7qi⭐ 99 stars· last commit 28d ago· 6 open issues

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.

—/10

// RATINGS

⭐GitHub Stars
⭐⭐ 99 on GitHubGitHub ↗

Growing

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

codex-collab

CI License: MIT Bun TypeScript

English | 中文

Collaborate with Codex from Claude Code. Run tasks, get code reviews, do parallel research, all without leaving your Claude session.

demo

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.

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

CommandDescription
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.

CommandDescription
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
nextBlock until something needs attention, print it in full with how to respond, then exit
approve <id>Approve a pending request

// HOW IT'S BUILT

// FILES

2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • SKILL.md7.8 KBupstream ↗
    ---
    name: codex-collab
    description: 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.
    ---
    
    # codex-collab
    
    codex-collab is a bridge between Claude and Codex. It communicates with Codex via the `codex app-server` JSON-RPC protocol, giving you structured, event-driven access to Codex's capabilities — prompting, code review, tool use, and file editing. Requires bun and the codex CLI on PATH (`codex-collab health` to verify).
    
    <!-- MODE:peer -->
    ## Choosing a path
    
    `codex-collab peer up` (foreground, seconds, idempotent) prints the workspace's address, `codex(myproject-a1b2c3)`; `ListAgents` shows it plus one entry per ongoing conversation. `SendMessage` to any of them is the normal way to talk to Codex. Use the CLI instead for `review`, for a result you need within the current turn (`run` blocks and exits with a status code), and for `--goal`, `--template`, or interactive approval policies. Both paths produce the same threads: a CLI-started thread can be messaged afterwards, and a messaged conversation appears in `codex-collab threads`.
    <!-- /MODE:peer -->
    
    <!-- MODE:cli -->
    ## Choosing a path
    
    Drive Codex interactions through the `codex-collab` CLI — `run` for tasks, `review` for code review, `--resume` for follow-ups. The ask channel is how Codex reaches you mid-task; `next` watches for those events.
    <!-- /MODE:cli -->
    
    <!-- MODE:peer -->
    ## Native Peer Messaging
    
    `SendMessage` to `codex(myproject-a1b2c3)` starts or continues a conversation. Any message may open with a header block of `key: value` lines, stripped before Codex sees the text. `topic:` names or selects the conversation (a later `topic:` switches to that conversation, or starts it); `model:`, `effort:` and `timeout:` (seconds per turn; default 3600 or `config timeout`) set the conversation's settings and, on a later message, change them from the next turn; `sandbox:` and `approval:` are fixed when the conversation starts (`approval:` accepts only `auto`, Codex Guardian — interactive approval prompts route to CLI clients and cannot work over messaging). Parsing stops at the first line that is not a recognized key, so ordinary prose is never consumed as a header.
    
    ```
    topic: auth refactor
    effort: xhigh
    sandbox: read-only
    
    Review the login flow and tell me what you would change.
    ```
    
    Each conversation appears as its own entry in `ListAgents` under its name. Reply to a message's `from` address to continue that specific conversation; a message to a busy conversation is delivered into the running turn and answered when it ends. Messaging is asynchronous: after sending, end your turn — do not poll, sleep, or block waiting for a reply. The reply arrives on its own as a cross-session message that wakes your session, even if you are busy with other work when it lands. A reply that lands mid-turn is folded into your context and renders in the Claude Code terminal, but not on remote views of the session (phone, web). Relaying its substance is normally enough; `codex-collab output <id> --last` is only needed when the transcript itself must carry the verbatim text — for a remote reader, or a reply held back by the receiver's `crossSessionInbound` setting.
    
    Messaged conversations write the same run records as CLI runs, so `codex-collab progress <id>`, `output`, `follow` and `kill` work on them; the `<id>` is the short ID in the conversation's address (`peer-<id>.sock`), and `codex-collab threads` lists them alongside CLI runs. A turn that exceeds its limit is stopped and reported as a timeout, so silence means Codex is still working — use `progress` to see what it is doing, not to wait. Codex may send a `[consult]` message mid-task when it needs your judgment; reply to that address to answer. If you don't, Codex proceeds on its own after a timeout.
    
    If `peer up` reports messaging unavailable (Windows, or an older Claude Code), the CLI handles everything.
    <!-- /MODE:peer -->
    
    Codex can also reach you directly: `codex-collab send` from a Codex session delivers a message to your session from a transient peer of its own, `codex(<thread>-<hash>-<task>)`, one per message; the message's last line names the Codex thread. Reply with `SendMessage` to that address. The reply is kept for the Codex session however long the work takes, until the task expires four hours after it was sent, so the message carries no deadline. In a session codex-collab started, time spent at a prompt the user answers through Remote Control does not count toward those hours, and once they answer one there are at least 60 minutes (`config linger`) left to reply. If `send` found no Claude session in the workspace, it resumed the background one it had last stopped, conversation intact, or else started one — a `claude(<workspace>-<hash>)` session in the working directory with none of the user's conversation, running in `auto` permission mode so it can carry out the work Codex hands it, that stops after 60 idle minutes by default (`config linger`).
    
    ## Codex's Own App-Server
    
    When Codex runs a shared app-server (`codex app-server daemon start`, bound at `~/.codex/app-server-control/app-server-control.sock`), the workspace broker attaches to it instead of spawning a private one. `config server` controls this: `auto` (default) attaches when the socket answers and falls back to a private server otherwise; `shared` insists on the shared server and fails without one; `private` never attaches. The environment variable `CODEX_COLLAB_SERVER` overrides the setting for one invocation; `CODEX_COLLAB_SERVER_SOCKET` overrides the control-socket path. The setting is read when a broker starts; `codex-collab peer up` restarts the workspace broker so a change applies. `health` prints which server the broker is on.
    
    Everything on a shared server is one space: turns you start render live in the Codex app or terminal UI, `threads --discover` marks threads other clients have open or running, and `run --resume <id>` joins such a thread. A prompt sent to a thread whose turn is already running is folded into that turn, and that turn stays the other client's: its approvals are answered where the user is looking, never by codex-collab. If the prompt carries overrides (`-m`, `-s`, `--approval`, `--dir`) or `--goal`, codex-collab refuses — those settings cannot apply to someone else's turn. The `codex` terminal UI declines every dynamic tool call on a thread it watches, which means a mid-turn consult to you is declined before you can answer; codex-collab delivers your answer into the running turn as an injected message. A turn you start on an idle thread is yours as usual. Without a shared server, Codex allows one writer per thread; a thread held elsewhere is refused with exit code 8 and a message listing the kinds of process that can hold it, though it cannot tell which one actually does. A thread the broker has used frees up about seven minutes (Codex 0.153.4) after the broker lets go of it — at turn end for a CLI run, when its thread peer retires (30 idle minutes) for a messaged conversation.
    
    ## Run Command
    
    The `run` command handles prompted tasks in one call: starts a thread, sends the prompt, waits for the turn to complete, and prints output.
    
    ```bash
    # Research task
    codex-collab run "what does this project do?" -s read-only --content-only
    
    # Implementation task
    codex-collab run "add input validation to the login form" --content-only
    
    # Resume an existing thread (preserves conversation context)
    codex-collab run --resume <id> "now check the error handling" --content-only
    
    # Specify working directory (omit -d if already in the project dir)
    codex-collab run "investigate the auth module" -d /path/to/project --content-only
    
    # Long or quote-riddled prompt: pass it on stdin with `run -` (no shell-quoting hazards)
    cat prompt.md | codex-collab run - --content-only
    ```
    
    **IMPORT
  • README.mdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/kevin7qi-codex-collab.md

// REPO STATS

99 stars
6 open issues
Last commit: 28d ago