kevin7qi/codex-collab/codex-skill

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.