# codex-collab

Adopt this skill: https://proskills.md/skills/other/kevin7qi-codex-collab

Page: https://proskills.md/skills/other/kevin7qi-codex-collab
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: SKILL.md
size: 8020
upstream: https://github.com/kevin7qi/codex-collab/blob/HEAD/SKILL.md

````text
---
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
````

## File: README.md
upstream: https://github.com/kevin7qi/codex-collab/blob/HEAD/README.md

````text
# codex-collab

[![CI](https://github.com/Kevin7Qi/codex-collab/actions/workflows/ci.yml/badge.svg)](https://github.com/Kevin7Qi/codex-collab/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Bun](https://img.shields.io/badge/runtime-Bun-f9f1e1?logo=bun)](https://bun.sh/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.3+-3178c6?logo=typescript&logoColor=white)](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.

![demo](.github/assets/demo.png)

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.

## 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](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, 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.

<details>
<summary>Where things get installed</summary>

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.

</details>

### Upgrading

An installed codex-collab can update itself — no manual `git pull` needed:

```bash
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`):

```bash
git pull
./install.sh    # Windows: powershell -ExecutionPolicy Bypass -File install.ps1
codex-collab health
```

<details>
<summary>More on upgrading</summary>

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

</details>

<details>
<summary>Development mode</summary>

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
```

</details>

## 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 <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](#peer-messaging).

<details>
<summary>Questions and approvals</summary>

| 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 |
````
