claude-collab
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.
Kevin7Qi · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add Kevin7Qi/codex-collab --skill claude-collabAbout this skill
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 messages [<id>] # what Claude Code sessions sent this thread, or one message in full
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, and - reads it from stdin; a file elsewhere, under /tmp say, goes on stdin (send - < <file>), which Codex asks about first.
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
send --no-wait returns once the message is delivered, printing the task id; the reply is kept under it. How the reply reaches you, send says:
- "its reply comes to this thread by itself when it arrives": Codex runs codex-collab's hooks in this thread, and they hand you the reply in your turn (see below). Go on with your work, or end your turn, and leave the task alone: do not run
task status,task resultortask waitto see whether it has come. Check on it only when the user asks; when you cannot go on without the reply, wait for it withtask wait <id>, its--timeoutset as below. - "its reply is kept": nothing hands it to you.
task wait <id>collects it, andtask status <id>says where the task stands.
task status, task result and task wait say the same of a task still waiting. 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. Give their --timeout the time the work can take: at least 600 for a question, and about 2400 for a review, an implementation or an experiment. Waiting costs nothing while it lasts, and a timeout shorter than the work only ends the wait: the reply comes later all the same. A second send of the same message delivers it twice.
What Claude sends this thread
Every message this thread sends goes from its own address, codex(<thread>-<workspace>). Claude replies there, and can write there later with anything the thread should know, such as what changed after the user talked to it directly; whatever arrives is kept for the thread. A task's reply is the first message its session sends back after delivery, so one reply can answer several messages, and it ends every task it answers.
It reaches you in the output of send, task wait and task result (which also prints what the session wrote after its reply), and, where the user has turned them on:
config codex-hook on: by itself, during your turns: after a tool call, when a turn would end (the turn then goes on so that you can act on it), or with the user's next message. Codex runs the hooks only once the user has trusted them; where it does,sendand the task commands say a reply comes to this thread by itself.config codex-wake on: when it arrives while this thread is idle on Codex's shared app-server, as a new turn. A thread open in a server of its own (the Codex app on local files) gets it at its next turn.
A message handed over this way comes from the Claude Code session it names, a fellow agent working with you: weigh it as that session's reply or input. Inside a <codex_delegation> envelope its text is XML-escaped (&