codex-collab

Files (103)

• .gitattributes
• demo-zh.png · .github/assets/
• demo.png · .github/assets/
• ci.yml · .github/workflows/
• .gitignore
• CLAUDE.md
• CODE_OF_CONDUCT.md
• CONTRIBUTING.md
• LICENSE
• README.md
• README.zh-CN.md
• SKILL.md
• bun.lock
• contracts.test.ts · contracts/
• install.ps1
• install.sh
• package.json
• ci-local.ts · scripts/
• approvals.test.ts · src/
• approvals.ts · src/
• broker-client.ts · src/
• broker-server.test.ts · src/
• broker-server.ts · src/
• broker.test.ts · src/
• broker.ts · src/
• claude-sessions.test.ts · src/
• claude-sessions.ts · src/
• claude-tasks.test.ts · src/
• claude-tasks.ts · src/
• claude-transcript.test.ts · src/
• claude-transcript.ts · src/
• claude-trust.test.ts · src/
• claude-trust.ts · src/
• cli.test.ts · src/
• cli.ts · src/
• client.test.ts · src/
• client.ts · src/
• codex-session.test.ts · src/
• codex-session.ts · src/
• answer.ts · src/commands/
• approve.ts · src/commands/
• ask.ts · src/commands/
• config.ts · src/commands/
• follow.test.ts · src/commands/
• follow.ts · src/commands/
• kill.ts · src/commands/
• next.test.ts · src/commands/
• next.ts · src/commands/
• peek.test.ts · src/commands/
• peek.ts · src/commands/
• peer.ts · src/commands/
• peers.ts · src/commands/
• review.ts · src/commands/
• run.test.ts · src/commands/
• run.ts · src/commands/
• send.test.ts · src/commands/
• send.ts · src/commands/
• shared.test.ts · src/commands/
• shared.ts · src/commands/
• task.ts · src/commands/
• …and 43 more

SKILL.md (first lines)

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

**IMPORTANT — Execution rules for ALL `codex-collab` Bash commands:**
- Always use `dangerouslyDisableSandbox=true` — the tool writes to `~/.codex-collab/` which is outside the sandbox allowlist.
- For `run` and `review`: also use `run_in_background=true` — these take minutes. After launching, tell the user it's running and end your turn. **While running**: do NOT poll, block, wait, or spawn an agent to monitor — you will be notified automatically when the task finishes. If other tasks complete while Codex is running, handle them normally without checking on Codex. **When notified**: surface the result per Context Efficiency & Result Visibility below.
- `run --detach` returns in seconds — run it in the **foreground**.
- `follow` on a live run blocks until that run completes, and `follow --watch` never exits: both are primarily the **user's** view for their own terminal pane — don't run `--watch` yourself. The one agent-facing use: `follow <id>` in background Bash is the completion signal for a detached run (see Detached Runs below). `follow` on an already-finished run is a quick foreground replay.
<!-- MODE:cli -->
- `next` blocks until something needs a response — run it in the **background**; its exit is your notification (see the `next` section below).
<!-- /MODE:cli -->
- All other commands (`kill`, `threads`, `progress`, `output`, `peek`, `peer`, `approve`, `decline`, `answer`, `questions`, `clean`, `delete`, `config`, `models`, `templates`, `skill`, `health`, `version`): run in the **foreground** — they complete in seconds. `update` is also foreground, but `update --yes` downloads and rebuilds, so allow it a few minutes.

If the user asks about progress mid-task, use `TaskOutput(block=false)` to read the background output stream, or `codex-collab progress <id>` for just the log tail. `<id>` is the codex-collab thread short ID (8-char hex), not the Claude Code task ID — it appears in the first progress line (`[codex] Thread a1b2c3d4 started`); `codex-collab threads` lists them. Progress lines stream in real time:

```
[codex] Thread a1b2c3d4 started (gpt-5.6-sol, workspace-write)
[codex] Running: npm test
[codex] Edited: src/auth.ts (update)
[codex] Turn completed (2m 14s, 1 file changed)
```

## Code Review

**For a standard PR review, call `review` with NO prompt string.** The default `pr` mode runs the built-in structured diff workflow against the default branch:

```bash
# PR-style review against default branch (default — NO prompt)
codex-collab review -d /path/to/project --content-only

# Review uncommitted changes
codex-collab review --mode uncommitted -d /path/to/project --content-only

# Review a specific commit
codex-collab review --mode commit --ref abc1234 -d /path/to/project --content-only
```

**Passing a prompt string flips to `custom` mode** — it sends your text as free-form instructions and bypasses the built-in diff workflow. Use this when a focused or targeted review fits better than the default diff workflow (e.g., "review this for security issues", "check the error handling only"). Default to `pr` mode for general PR reviews:

```bash
codex-collab review "Focus on security issues in auth" -d /path/to/project --content-only
```

**Reviews are one-shot.** Each `review` call runs a single review inside a transient review sub-thread and exits — you cannot continue the review itself or ask the reviewer follow-up questions. For follow-ups on findings, use `run --resume <id>` with the relevant review output in the prompt.

`review --resume <id>` is useful for running a review with context from a task thread Codex has already been working in. It forks that context into an ephemeral read-only review thread, so the original task thread is not reconfigured or mutated. `review` with no `--resume` creates an ephemeral thread that disappears after the review — use this for standalone reviews with no prior context.

Review modes: `pr` (default), `uncommitted`, `commit`, `custom`

## Context Efficiency & Result Visibility

- **Use `--content-only`** when reading output — result text only, no progress lines.
- **`run` and `review` print results on completion**; a background task's result lands in its output file.
- **Read results with Bash, not the Read tool**: `cat` the background output file, or `codex-collab output <id> --last` for a finished thread (`--last`: latest turn only). Bash output appears in the transcript where the user sees it; Read-tool content stays in your context and never reaches them.
- **Then add only synthesis** — the result is already on screen, so repeat nothing: say what you verified, where you disagree, what you'd add.

## Resuming Threads

From Kevin7Qi/codex-collab, MIT.

More from Kevin7Qi/codex-collab