---
name: claude-collab
description: Use when the user asks to invoke, delegate to, or collaborate with Claude (Claude Code) on any task. Also use PROACTIVELY when handing part of the work to Claude, or an independent non-Codex perspective, would add value — implementation, review, second opinions on code, plans, architecture, or design decisions.
---

# Claude Code peers

Claude Code sessions in this workspace are peers you can collaborate with: delegate a task, divide implementation work, or review each other's output. Each is a separate agent with its own context, working in the same directory — often the session the user is talking to in another terminal.

codex-collab is the whole path to them: it records every message as a task and keeps its reply, and it starts, resumes and stops the sessions it hands work to. A session started any other way (`claude --bg`, a terminal) is outside most of that: `send` can message it while it is live, but codex-collab never stops it, `peers stop` refuses it, and it is never resumed.

## Commands

    codex-collab peers                    # who is live here: name, idle or busy, kind
    codex-collab send <name> "message"    # hand that session a task and wait for its reply
    codex-collab send "message"           # the only live session (the user's, if theirs is the one), or one started for you
    codex-collab send --new "message"     # a new session started for you, even while the user's is live
    codex-collab task wait <id>           # go on waiting for a task's reply
    codex-collab task result <id>         # print a task's reply, if it has come
    codex-collab task status <id>         # where a task stands
    codex-collab tasks                    # all tasks sent from this workspace
    codex-collab peers stop [<name>]      # stop a session codex-collab started
    codex-collab send --help              # which session each form of send reaches; every option

Every `send` is a task with an id, printed when the message is delivered. `--timeout <sec>` (default 600) bounds how long the command waits. The task continues past it for four hours from sending (or the `--timeout`, if longer), not counting time a session codex-collab started spends at a prompt the user can answer through Remote Control, and with at least 60 minutes (`config linger`) after the user answers one; a reply in that time is kept under the id; after that the task is `expired`. `--no-wait` returns once the message is delivered; `task wait <id>` collects the reply afterwards. `--file <path>` reads the message from a file inside the folder this Codex session works in; `-` reads it from stdin.

## Handing work off without waiting

    # a new session, on the model and effort the task calls for
    codex-collab send --new --no-wait --model <model> --effort <level> --file task.md

    # a session that is already live, by its name
    codex-collab send "<name>" --no-wait --file task.md

    # later: where it stands, and the reply once it has come
    codex-collab task status <id>
    codex-collab task result <id>         # or task wait <id>, which waits for it

`send --no-wait` returns once the message is delivered, printing the task id; the reply is kept under it. `run --detach` belongs to codex-collab's other side, the runs Claude starts in Codex.

Simple questions usually return quickly; reviews, implementations and experiments can take minutes to tens of minutes while the session reads, edits and tests. `send` and `task wait` block until the reply lands. A second `send` of the same message delivers it twice.

## Choosing a model

`--model <model>` (`-m`) and `--effort <level>` (`-r`) set the model and effort when `send` starts or resumes a session. With no `--effort`, it runs at `high`, or at the user's `config spawn-effort`. The choice holds until the session next stops. The levels, lowest first, are `low`, `medium`, `high`, `xhigh` and `max`; a model without `xhigh` or `max` (`claude-opus-4-6`, for one) runs those at `high`. `codex-collab peers` shows what a started session runs on; `send` reports when a choice could not apply. A session the user opened keeps the model and effort they chose. The user's account pays for a session `send` starts, so choose the model and effort with the task's complexity and cost in mind.

`codex-collab models --claude` prints the available models. `--model` also accepts any full version string.

- **fable** — the most capable: hard design problems, deep debugging, long multi-step work.
- **opus** — balanced everyday model: routine coding, reviews, explanations.
- **sonnet** — fastest and cheapest: lookups, summaries, simple questions.

## Working with a session

- Neither agent sees the other's conversation. Both share the same working directory and can write the same files.
- Each `send` is one task, and a session has one conversation: tasks sent to the same session share its context and are taken one after another. A message to a busy session joins the turn in progress, and is answered when the session gets to it.
- codex-collab keeps one session of its own per workspace. A workspace is a git repository (each worktree of it apart), whichever of its folders `send` runs in; outside any repository, it is the folder itself. So outside a repository, a folder of its own gives a task a session of its own: `codex-collab send -d <folder> --new …` starts one working there, and tasks that need separate contexts at the same time can each have one. Inside a repository, there is one.

## Mechanics

- `send` and `peers stop` reach Claude Code over a local socket, which the sandbox blocks: they run outside the sandbox. `peers`, `task` and `tasks` work inside it. `codex-collab config codex-rule on` removes the per-command approval for `send` and `peers stop` when each is a plain command; a redirect, heredoc or pipe (`send - < task.md`) makes it a shell script, which Codex asks about first, and `--file` keeps it plain.
- The outcome line is `task: <id>  status: <status>`; a message that could not be delivered gets the reason in its place. Exit codes: **0** replied. **3** no reply yet; the task continues. **5** a session codex-collab started stopped at a prompt nobody could answer, or one the user could answer through Remote Control and had not for 60 minutes (`config linger`); codex-collab stopped it, and its conversation is kept (when it would not stop, the error says so). **1** no reply will come: undeliverable, session gone, the turn of a session codex-collab started ended on an error, or the task expired. The error is reported as the session recorded it, e.g. `429 rate_limit at <time>`, `500 server_error at <time> (3 since delivery)`.
- A task's own status is `pending`, `running`, `replied`, `blocked`, `lost`, `failed` or `expired`; it is what the `status:` line carries. `task status <id>` reads it once, along with the session's status while the task is open: `busy` (turn in progress), `shell` (turn ended with a command of its own still running), `idle` (nothing in hand), `waiting` (stopped at a prompt).
- If a turn ends with an error, the task is marked as failed when codex-collab started the session, since nothing there will set it going again. In a session the user is working in, the task stays open and the error is recorded on it. Nothing is sent to the session on the caller's behalf.
- With no session live, `send` starts one named `claude(<workspace>-…)`. It stops after 60 idle minutes (`config linger`), or four hours after it started once it has nothing in hand and no task waiting on it. While the user can reach it through Remote Control, a prompt in it is theirs to answer and its age does not stop it; a prompt unanswered for 60 minutes does. A session stopped within the past week is resumed with its conversation, by the next `send` or by a `send` that names it. `--new` starts a new one instead, also while the user's sessions are live, and never messages one of theirs; there is one such session per workspace, so `--new` is refused while it is live. Any other name that is not live is refused. `codex-collab send --help` lists which session each form reaches. A new session starts from the working directory with none of the user's conversation, in Claude Code's `auto` permission mode, and can edit files and run commands.
- Claude Code starts a session only in a folder the user has trusted in Claude Code, or one below it; inside a git repository, a trusted folder counts only up to the repository's root. Elsewhere, such as a new folder under `/tmp`, `send` is refused with the folder and the reason. Trusting a folder is the user's to do: in a terminal, or, once they have turned on `spawn-trust codex`, in Codex, after which `send` marks a folder Codex trusts as trusted in Claude Code itself and says so. `config spawn-trust codex` is refused when Codex runs it. A stopped session there stays resumable.
- `peers stop <name>` ends a session codex-collab started, through the same mechanism that started it; its conversation is kept. A session codex-collab did not start is refused.
- Claude Code restarts a background session that dies in the middle of a turn (crashed, killed or signalled) as a new process, and has it continue that turn. A task waiting on it goes on waiting, and `task status` shows the restart. If the session does not come back, or does not pick the turn up again, the task ends `lost` with that reason.
- A user session in `bypassPermissions` mode holds messages from other sessions until the user approves them, unless `crossSessionInbound` is `accept`. From the caller's side it is a task that stays running.