codex-collab

codex-collab

codex-collab は Claude と Codex をつなぐブリッジです。codex app-server JSON-RPC プロトコルを介して Codex と通信し、プロンプトの送信、コードレビュー、ツールの使用、ファイル編集など、Codex の機能に構造化されたイベント駆動型の方法でアクセスできます。bun と PATH 上の codex CLI が必要です（codex-collab health で確認できます）。

パスの選択

codex-collab peer up（フォアグラウンドで実行し、数秒で起動する冪等なコマンド）を実行すると、ワークスペースのアドレス codex(myproject-a1b2c3) が表示されます。ListAgents にはこのアドレスと、進行中の会話ごとのエントリが表示されます。Codex との通常のやり取りには、いずれかに SendMessage を送信します。review、現在のターン内に結果が必要な場合（run はブロックして終了コードを返します）、および --goal、--template、対話型の承認ポリシーを使用する場合は、代わりに CLI を使います。どちらの方法でも同じスレッドが作成されます。CLI で開始したスレッドには後からメッセージを送信でき、メッセージを送信した会話は codex-collab threads に表示されます。

パスの選択

Codex とのやり取りには codex-collab CLI を使います。タスクには run、コードレビューには review、追加のやり取りには --resume を使用します。ask チャネルを通じて Codex はタスクの途中でユーザーに連絡できます。next はそのようなイベントを監視します。

ネイティブのピアメッセージング

codex(myproject-a1b2c3) に SendMessage を送ると、会話が開始または継続されます。任意のメッセージの冒頭には key: value 形式の行からなるヘッダーブロックを付けることができ、Codex がテキストを確認する前に取り除かれます。topic: は会話に名前を付けるか、会話を選択します（後続の topic: はその会話に切り替えるか、会話を開始します）。model:、effort:、timeout:（ターンあたりの秒数。デフォルトは 3600 または config timeout）は会話の設定を指定し、後続のメッセージで設定を変更すると次のターンから反映されます。sandbox: と approval: は会話の開始時に固定されます（approval: で指定できるのは auto のみです。Codex Guardian — 対話型の承認プロンプトは CLI クライアントに送られるため、メッセージング経由では機能しません）。解析は認識済みのキーではない最初の行で停止するため、通常の文章がヘッダーとして処理されることはありません。

topic: auth refactor
effort: xhigh
sandbox: read-only

Review the login flow and tell me what you would change.

各会話は、その名前で ListAgents に個別のエントリとして表示されます。特定の会話を続けるには、メッセージの from アドレスに返信してください。処理中の会話にメッセージを送ると、実行中のターンに渡され、そのターンが終わると返信されます。メッセージングは非同期です。送信後はターンを終了してください。返信を待つためにポーリング、スリープ、ブロックをしてはいけません。返信は独立したクロスセッションメッセージとして届き、到着時にほかの作業で忙しくしていても、セッションが起動します。ターンの途中で届いた返信はコンテキストに取り込まれ、Claude Code のターミナルに表示されますが、セッションのリモートビュー（スマートフォン、ウェブ）には表示されません。通常は内容を伝えるだけで十分です。逐語的なテキストをトランスクリプトに含める必要がある場合（リモートの閲覧者向け、または受信側の crossSessionInbound 設定によって返信が保留されている場合）に限り、codex-collab output <id> --last が必要です。

メッセージを送信した会話も CLI 実行と同じ実行記録を書き込むため、codex-collab progress <id>、output、follow、kill を使用できます。<id> は会話のアドレス（peer-<id>.sock）に含まれる短い ID で、codex-collab threads には CLI 実行と並んで表示されます。ターンが制限時間を超えると停止し、タイムアウトとして報告されます。そのため、応答がない場合は Codex がまだ作業中です。待機するのではなく、progress で作業状況を確認してください。判断が必要なとき、Codex はタスクの途中で [consult] メッセージを送ることがあります。回答するには、そのアドレスに返信してください。返信しない場合、タイムアウト後に Codex が独自に作業を続けます。

peer up でメッセージングが利用できないと報告された場合（Windows、または古いバージョンの Claude Code）は、すべて CLI が処理します。

Codex から直接あなたに連絡することもできます。Codex セッションから codex-collab send を実行すると、そのメッセージ専用の一時的なピア codex(<thread>-<hash>-<task>) から、あなたのセッションにメッセージが届きます。メッセージの最終行には Codex スレッドが記載されています。そのアドレスに SendMessage で返信してください。返信は、作業にかかる時間にかかわらず、タスクの送信から 4 時間後に期限切れになるまで Codex セッションに保持されます。そのため、メッセージに期限は記載されません。codex-collab が開始したセッションでは、ユーザーが Remote Control 経由で回答するプロンプトで費やした時間はこの時間に含まれません。また、ユーザーが回答した後は、返信まで少なくとも 60 分（config linger）あります。send がワークスペース内に Claude セッションを見つけられなかった場合は、会話を保持したまま、最後に停止したバックグラウンドセッションを再開します。それがなければ、新しいセッションを開始します。新しいセッションは、作業ディレクトリで実行される claude(<workspace>-<hash>) セッションで、ユーザーとの会話は含まず、Codex から渡された作業を実行できるよう auto 権限モードで動作し、デフォルトでは 60 分間アイドル状態が続くと停止します（config linger）。

Codex 独自の App-Server

Codex が共有 app-server（codex app-server daemon start、~/.codex/app-server-control/app-server-control.sock で待ち受け）を実行している場合、ワークスペースブローカーは専用の app-server を起動せず、そのサーバーに接続します。これを制御するのが config server です。auto（デフォルト）はソケットが応答すると共有サーバーに接続し、応答しない場合は専用サーバーにフォールバックします。shared は共有サーバーへの接続を必須とし、利用できない場合は失敗します。private は共有サーバーに接続しません。環境変数 CODEX_COLLAB_SERVER は一度の実行に限り設定を上書きし、CODEX_COLLAB_SERVER_SOCKET は制御ソケットのパスを上書きします。設定はブローカーの起動時に読み込まれます。変更を適用するには、codex-collab peer up を実行してワークスペースブローカーを再起動してください。health では、ブローカーが接続しているサーバーを確認できます。

共有サーバー上では、すべてがひとつの空間にあります。あなたが開始したターンは Codex アプリまたはターミナル UI にリアルタイムで表示され、threads --discover では、ほかのクライアントが開いている、または実行中のスレッドに印が付きます。また、run --resume <id> でそのようなスレッドに参加できます。ターンがすでに実行中のスレッドに送信したプロンプトはそのターンに取り込まれ、そのターンは引き続き別のクライアントのものです。その承認はユーザーが見ている場所で応答され、codex-collab が応答することはありません。プロンプトにオーバーライド（-m、-s、--approval、--dir）または --goal が含まれている場合、codex-collab は実行を拒否します。これらの設定は、ほかのユーザーのターンには適用できないためです。codex ターミナル UI は、監視中のスレッドに対する動的なツール呼び出しをすべて拒否します。そのため、ターンの途中であなたへの相談が行われても、あなたが回答する前に拒否されます。codex-collab は、あなたの回答を注入メッセージとして実行中のターンに届けます。アイドル状態のスレッドであなたが開始したターンは、通常どおりあなたのものです。共有サーバーがない場合、Codex はスレッドごとに書き込み可能なクライアントをひとつに制限します。別のプロセスが使用中のスレッドは、終了コード 8 と、スレッドを使用できるプロセスの種類を列挙したメッセージとともに拒否されます。ただし、実際にどのプロセスが使用しているかは判別できません。ブローカーが使用したスレッドは、ブローカーが解放してから約 7 分後（Codex 0.153.4）に再び使用可能になります。CLI 実行ではターン終了時、メッセージのやり取りをする会話ではスレッドのピアが終了した時（30 分間アイドル状態になった時）に解放されます。

Run Command

run コマンドは、スレッドを開始し、プロンプトを送信して、ターンの完了を待ち、出力を表示するという一連の処理を 1 回の呼び出しで実行します。

# 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

重要 — すべての codex-collab Bash コマンドの実行ルール：

• 必ず dangerouslyDisableSandbox=true を使用してください。ツールはサンドボックスの許可リスト外にある ~/.codex-collab/ に書き込みます。

• run と review では、run_in_background=true も使用してください。これらの処理には数分かかります。起動したら、処理中であることをユーザーに伝えて、ターンを終了してください。実行中は、ポーリング、ブロック、待機、監視用のエージェントの起動を行わないでください。タスクが完了すると、自動的に通知されます。Codex の実行中にほかのタスクが完了した場合は、Codex の状態を確認せず、通常どおり対応してください。通知を受けたら、以下の「コンテキストの効率化と結果の提示」に従って結果を提示してください。

• run --detach は数秒で戻るため、フォアグラウンドで実行してください。

• 実行中の処理に対する follow は、完了までブロックします。follow --watch は終了しません。どちらも主にユーザーが自分のターミナルペインで使うものです。エージェント側では --watch を実行しないでください。エージェント側での唯一の用途は、バックグラウンド Bash で follow <id> を実行し、デタッチされた処理の完了シグナルを受け取ることです（「デタッチされた処理」を参照）。すでに完了した処理に対する follow は、フォアグラウンドで速やかに再生されます。

• next は応答が必要になるまでブロックするため、バックグラウンドで実行してください。終了が通知となります（以下の next セクションを参照）。

• それ以外のすべてのコマンド（kill、threads、progress、output、peek、peer、approve、decline、answer、questions、clean、delete、config、models、templates、skill、health、version）は、数秒で完了するため、フォアグラウンドで実行してください。update もフォアグラウンドで実行しますが、update --yes はダウンロードと再ビルドを行うため、数分かかることがあります。

タスクの途中でユーザーから進捗を尋ねられた場合は、TaskOutput(block=false) でバックグラウンド出力ストリームを読み取るか、ログ末尾だけを確認するには codex-collab progress <id> を使用してください。<id> は codex-collab スレッドの短い ID（8 桁の 16 進数）であり、Claude Code のタスク ID ではありません。最初の進捗行（[codex] Thread a1b2c3d4 started）に表示されます。スレッドの一覧は codex-collab threads で確認できます。進捗行はリアルタイムで出力されます。

[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

標準的な PR レビューでは、プロンプト文字列を指定せずに review を呼び出してください。 デフォルトの pr モードでは、デフォルトブランチを対象に、組み込みの構造化された差分ワークフローを実行します。

# 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

プロンプト文字列を渡すと、custom モードに切り替わります。入力したテキストを自由形式の指示として送信し、組み込みの差分ワークフローを迂回します。デフォルトの差分ワークフローよりも、焦点を絞ったレビューや対象を限定したレビューが適している場合に使用してください（例：「セキュリティ上の問題がないか確認する」「エラーハンドリングだけを確認する」）。一般的な PR レビューでは、デフォルトで pr モードを使用してください。

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

レビューは 1 回限りです。 各 review 呼び出しは、一時的なレビュー用サブスレッドでレビューを 1 回実行して終了します。レビュー自体を続けたり、レビュー担当者に追加の質問をしたりすることはできません。指摘内容について追加で確認する場合は、関連するレビュー出力をプロンプトに含めて run --resume <id> を使用してください。

review --resume <id> は、Codex がすでに作業しているタスクスレッドのコンテキストを引き継いでレビューを実行する場合に便利です。このコマンドは、そのコンテキストを一時的な読み取り専用のレビュー用スレッドに分岐するため、元のタスクスレッドの設定や状態は変更されません。--resume を付けずに review を実行すると、レビュー終了後に破棄される一時スレッドが作成されます。事前のコンテキストがない単独のレビューには、こちらを使用してください。

レビューのモード：pr（デフォルト）、uncommitted、commit、custom

コンテキスト効率と結果の表示

• 出力を読むときは --content-only を使用してください。進捗行を含まず、結果テキストのみが表示されます。
• run と review は完了時に結果を出力します。バックグラウンドタスクの結果は出力ファイルに書き込まれます。
• 結果は Read ツールではなく Bash で読み取ってください。バックグラウンドの出力ファイルを cat するか、完了したスレッドなら codex-collab output <id> --last を実行します（--last：最新のターンのみ）。Bash の出力はユーザーに表示されるトランスクリプトに現れますが、Read ツールの内容はコンテキスト内にとどまり、ユーザーには届きません。
• その後は要点だけを追加してください。結果はすでに画面に表示されているため、繰り返す必要はありません。確認したこと、意見が異なる点、追加したいことを述べてください。

スレッドの再開

連続するタスクが同じプロジェクトに関係する場合は、既存のスレッドを再開してください。Codex は会話履歴を保持するため、「では、見つかった問題を修正して」や「テストも確認して」といったフォローアップは、Codex が前回のやり取りのコンテキストを持っている場合によりうまく進みます。タスクに関連性がない場合や、別のプロジェクトを対象とする場合は、新しいスレッドを開始してください。

以前のタスクを続ける、またはフォローアップするようユーザーから依頼されたものの、スレッド ID がコンテキストにない場合は、次の手順で探してください。

1. codex-collab threads --discover — 最近のスレッド上位 5 件（サーバー＋ローカル）を確認します。このセッション内でスレッドが開始されている場合は、codex-collab threads --session を使うと対象をそのスレッドに絞れます。
2. どのスレッドが該当するか不明な場合は、候補の codex-collab peek <id> を実行して、最後のやり取りを確認します。
3. スレッドが非常に長く、peek だけでは不十分な場合は、codex-collab peek <id> --limit 100 --full を使ってサブエージェントを起動し、要約を依頼します。こうすると、大量の出力を自分のコンテキストに持ち込まずに済みます。
4. codex-collab run --resume <id> "..." を実行して続行します。

再開が必要な場合に限り --discover を実行してください。これは必要に応じて行う検索です。

--resume フラグは、どちらの ID 形式も受け付けます。

• --resume <short-id> — 8 文字の 16 進数短縮 ID（a1b2 のようなプレフィックス指定に対応）
• --resume <thread-id> — Codex スレッド ID 全体（UUID。例：019d680c-7b23-7f22-ab99-6584214a2bed）

状況	操作
同じプロジェクトで、新しいプロンプトを実行する	codex-collab run --resume <id> "prompt"
同じプロジェクトで、レビューを依頼する	codex-collab review --resume <id>
別のプロジェクト	新しいスレッドを開始する
スレッドが停止／エラーになった	codex-collab kill <id> を実行してから、新しいスレッドを開始する

スレッド ID が分からなくなった場合は、codex-collab threads を使ってアクティブなスレッドを探してください。

切り離した実行と追跡

切り離すタイミング： 基本的にはバックグラウンドで run を実行します。ターンが終了しても実行は継続し、完了通知も自動で届きます。--detach を使うのは、次の2つの状況に限ります。（1）ターンを現在の Claude セッションの終了後も継続させる必要がある場合。バックグラウンドタスクはセッションの終了または再起動時に強制終了され、進行中のターンが中断されます。一方、切り離した実行は継続し、後から output <id> --last で結果を取得できます。（2）ユーザーが自身のターミナルから操作していて、そのシェルから独立してターンを実行したい場合。定型的なタスクは切り離さないでください。自動完了通知が届かなくなります（通知を再び受け取る方法は以下をご覧ください）。

run --detach はターンを切り離されたランナーに引き渡し、ターンが実際に実行を開始するとすぐに戻ります。ターンの実行期間は呼び出し元のシェルから切り離されるため、シェルやセッションが終了しても強制終了されません。

codex-collab run "large refactor task" --detach --approval auto
# [codex] Detached: thread a1b2c3d4 running (gpt-5.6-sol)
# [codex]   Follow:   codex-collab follow a1b2c3d4

follow [id] は実行中のスレッドをリアルタイムで表示します。現在までの実行内容を再生した後、実行が終了するまでイベント（終了コード付きのコマンド、ファイルの編集、Guardian の判断、承認プロンプト）をストリーミングし、最終ステータスで終了します（終了コード 0 = 完了）。ID を指定しない場合は、ワークスペースのアクティブな実行に接続します（または最新の実行を再生します）。そのため、ユーザーは codex-collab follow と入力するだけで構いません。すでに終了した実行に対しては、その実行を再生して終了するため、何が起きたかを手早く確認する方法としても使えます。

複数ターンにわたる Claude ⇄ Codex の会話では、別のターミナルペインで codex-collab follow --watch を開いておくようユーザーに提案してください。 ターンごとに終了することはなく、新しい実行を自動的に検出します（同時進行中のスレッド間でも、各実行は開始順に一度だけ表示されます。別の実行を表示している間に終了した実行は、短い再生として表示されます）。専用の色分けされた表示で、モデルコンテキストを一切消費せず、Ctrl-C で終了できます。複数のスレッドを並行して実行していて、ユーザーがスレッドごとに専用のペインを使いたい場合は、follow <id> --watch で対象を1つのスレッドに限定してください。

切り離した実行の完了通知（エージェント向け）： 切り離し元のプロセスは、ターンが完了したときではなく、開始したとき に終了します。そのため、run --detach をバックグラウンドで実行しても、完了通知は届きません。完了通知が必要な場合は、バックグラウンドの Bash で codex-collab follow <id> を実行します。実行が終了状態に達すると終了します（終了コード 0 = 完了）。その終了が通知になります。

ポーリングせずに質問や承認を監視する（next）

codex-collab next は、ワークスペース内で応答が必要な最初のイベント（ask チャンネルの質問（下記「Ask チャンネル」を参照）または保留中の対話型承認）が発生するまで待機し、その内容を全文（質問本文と回答コマンド。後から questions <id> を実行する必要はありません）表示して終了します。終了コード：0 イベントを通知 · 10 ワークスペースがアイドル状態（実行中の処理も保留中の項目もありません。自動クリーンアップされるため、実行終了後に監視プロセスが残ることはありません） · 3 明示的に --timeout <sec> を指定した場合のみ。

回答可能なイベントが発生する実行では、必ず監視を開始してください：ask チャンネルを使用する実行（--template collab）、または処理がブロックされる可能性のある承認モード（on-request、on-failure、untrusted）が対象です。--approval never で ask テンプレートを使用しない場合、イベントは発生しないため、監視は不要です（実行終了時に 10 で終了します）。auto では Guardian が承認を自律的に処理しますが、質問は引き続き通知されます。

基本的な使い方：実行と next を Bash のバックグラウンドコマンドとして同時に起動し、そのまま作業を続けます。next が終了したら、それが通知です。next が監視するのは単一のワークスペースです。実行時と同じ -d を指定して監視してください（引数なしの next はカレントディレクトリのワークスペースのみを監視し、ほかのワークスペースのイベントを確認することなく 10 で終了します）。

codex-collab next -d /path/to/project   # in background Bash; its exit = something needs you
# → Question q7f3a2c1  expires in 9m
#
#    <full question text>
#
#    Answer with: codex-collab answer q7f3a2c1 "<text>" -d '/path/to/project'

回答と監視の再開は、同じメッセージ内で行ってください：next が終了したら、answer（または approve）と新しい next を並列のツール呼び出しとして実行します。これにより、各イベントに必要な起動は1回、応答ターンも1回だけです。再開するのは、回答してからにしてください。next は通知済みイベントを記憶しないため、質問が保留中のまま再開すると、同じイベントがすぐに再度通知されます。待機中の next はコンテキストを一切消費せず、長時間の実行では何度も質問されることがあります。実行が完了する（実行自体の終了が通知されます）か、next が 10 で終了するまで、このループを続けてください。

実行を所有するプロセスにかかわらず、ディスク上の状態がこれらすべてを支えています。実行レコード（workspaces/*/runs/<runId>.json）には、ブロック中の pendingQuestion と pendingApproval、解決済みの監査記録として questions[] が保存されます。

Ask チャネル（Codex が質問し、あなたが回答）

長時間の実行や自律的な実行では、Codex は実行の成否をあなたの返答に委ねることなく、ターンの途中で一時停止して質問できます。組み込みの collab テンプレートを使って実行を開始し、このチャネルについて教えます。

codex-collab run "large refactor task…" --template collab --timeout 3600

ターンの途中で Codex は codex-collab ask "…" を実行します。これは最大 10 分間待機し、その後、Codex 自身のコンテキストに出力される次のいずれかの結果になります。あなたからの回答（方向付け）、または回答がない旨を示す通知（フェイルオープン。実行は続行され、未回答の質問は実行記録に残ります）。質問するのは判断を仰ぐためであり、許可を求めるためではありません。承認とは異なり、質問によって実行が終端的にブロックされることはありません。テンプレートではチャネルとそのコストを宣言しますが、意図的にルールは定めていません。質問するかどうか、いつ質問するかは Codex 自身が判断します。

以下のメールボックスは、Codex がターン途中の質問に使うチャネルです。また、あらゆる場合のフォールバック先です。

長い collab スレッドを再開するときは、チャネルについてもう一度伝えてください。 チャネルの指示は最初のプロンプトに含まれます。また、長いスレッドは古いものから順に圧縮されます。そのため、再開プロンプトには自分の言葉で一文含めてください（例：「コラボレーションチャネルは引き続き利用できます。codex-collab ask で私に連絡できます」）。Codex に必要なのは要点だけです。仕組みは codex-collab --help から再確認できます。

保留中の質問は、進行状況ストリーム（および follow）に表示されます。

[codex] QUESTION FROM CODEX (expires in 10m)
[codex]   Migrating auth to JWT next. Drop the FK constraints or dual-write?
[codex]   Answer: codex-collab answer q7f3a2c1 "<text>" -d '/path/to/project'

次の優先順位で対応してください。

1. 自分のコンテキストから回答する — 実行を開始したのはあなたであり、通常、質問への回答に必要な情報を持っています。質問は割り込み優先度が高いため、検討している間も Codex は期限までの時間を消費しています。
2. 権限を超える好みや製品上の判断であれば、ユーザーに確認する — 質問を伝え、ユーザーの回答を送り返してください。
3. 明示的に辞退する — 何もせずに期限切れにするのではなく、codex-collab answer <id> "Your call — proceed and note the decision" を使ってください。これにより、意図的な「続行」と、回答できる人がいなかった状況を監査記録で区別できます。

回答の作り方：トークンではなく、判断を伝えます。 選択、その理由、Codex が判断を変えるか再度質問すべき条件を伝えてください。理由のない「はい」では一つの判断しか方向付けられませんが、理由を添えた回答なら、その後の 10 回の判断にも役立ちます。長い回答を送る場合は、codex-collab answer <id> - が標準入力を読み取ります。

codex-collab questions            # list pending questions (id, age, time left)
codex-collab questions <id>       # full text of one question (list view clips long ones)
codex-collab answer <id> "text"   # answer one (prefix matching works)

承認

デフォルトでは、Codex はすべてのアクションを自動承認します（--approval never）。より厳密に制御するには、次のようにします。

# Require approval for Codex-initiated actions
codex-collab run "refactor the auth module" --approval on-request --content-only

# Guardian decides each request autonomously — approve or deny, never blocking on a human
codex-collab run "refactor the auth module" --approval auto --content-only

--approval auto を指定すると、Guardian は各リクエストを単独で承認または拒否します。対話型フローにエスカレーションすることはないため、自動実行がブロックされることはありません。判断は進行状況ストリームに Guardian approved (low risk): … のように表示され、完全なペイロードはスレッドログに記録されます。判断を要するケースや拒否は、リスクレベル、ユーザーによる承認の評価、理由を記載した Guardian warning: … の行にも表示されます。Guardian は、そのアクションをユーザーが求めたかどうかを重視します。ユーザーが明示的に求めたコマンドは承認度が高く、通常は承認されます。Guardian の役割は、モデルが権限を超えて行動するのを防ぐことです。

Guardian がアクションを拒否しても、実行は続行され（エージェントは回避策を探します）、拒否は進行状況のヒントとともにローカルに保存されます（Override available: codex-collab approve --guardian <review-id>）。ユーザーがそのアクションは問題なかったと判断した場合は、次のようにします。

codex-collab approve --guardian               # list pending denials
codex-collab approve --guardian <review-id>   # override one (prefix ok)

オーバーライドは、そのスレッド内の該当するアクションに対するユーザーの承認を記録します。すぐに実行されることはありません。エージェントはスレッドの次回実行時に再試行します（codex-collab run --resume <short-id> "continue"）。承認の対象はその特定のアクションのみであり、類似するアクションは対象外です。

対話型ポリシー（on-request、on-failure、untrusted）では、承認リクエストは次のように表示されます。

[codex] APPROVAL NEEDED
[codex]   Command: rm -rf node_modules
[codex]   Approve: codex-collab approve <approval-id>
[codex]   Decline: codex-collab decline <approval-id>

approve または decline で回答してください。

codex-collab approve <approval-id>
codex-collab decline <approval-id>

CLI リファレンス

run、review、--detach、follow の使用例は上記の各セクションにあります。以下は、その他のコマンドです。

codex-collab output <id> [--last]       # Full log for thread (--last: only the latest turn's output)
codex-collab progress <id>              # Recent activity (tail of log)
codex-collab threads [--all|--discover] # List threads (--discover: include server-side, top 5)
codex-collab threads --session          # Only threads the current session has run
codex-collab peek <id> [--limit N --full] # Recent conversation slice from server
codex-collab kill <id> [--clear]        # Stop a running thread; an active goal is paused first (--clear abandons it)
codex-collab delete <id>                # Archive thread (recoverable via `codex unarchive`), delete local files
codex-collab delete <id> --purge        # Permanently delete server-side instead — NOT recoverable; needs explicit user intent
codex-collab clean                      # Delete old logs, stale mappings, old question files
codex-collab approve <id> | decline <id> # Answer a pending approval

codex-collab peer [up]                  # Peer status; `peer up` starts or restarts the workspace broker (and its peer)


codex-collab peer up                    # Start or restart the workspace broker (applies a changed `config server`)


codex-collab answer <id> "text"         # Answer a pending ask-channel question (see The Ask Channel)
codex-collab questions [id]             # List pending questions (with an ID: show its full text)
codex-collab next [--timeout <sec>]     # Block until a question/approval needs you; print it in full
                                        # (exit 0 = event, 10 = workspace idle, 3 = timeout)
codex-collab ask "q" [--timeout <sec>]  # (invoked BY CODEX mid-turn, not by you) post a question, wait, fail open

codex-collab config [key] [value] [--unset] # Show/set/unset persistent defaults (model, mode, server, reasoning, sandbox, approval, timeout, memory)
codex-collab skill sync [--yes]         # Regenerate installed SKILL.md — diff first, --yes applies (see Staying Up to Date)
codex-collab update [--check|--skip|--yes] # Check for / install a newer release (see Staying Up to Date)
codex-collab models | templates | health | version

注：jobs は非推奨の threads のエイリアスとして引き続き使用できます。

オプション

フラグ	説明
-m, --model <model>	モデル名（デフォルト：auto — 利用可能な最新モデル）
-r, --reasoning <level>	推論の強度：none、minimal、low、medium、high、xhigh、max、ultra（デフォルト：auto — モデルがサポートする最高レベル。xhigh まで）
-s, --sandbox <mode>	サンドボックス：read-only、workspace-write、danger-full-access（デフォルト：workspace-write）。review ではこのフラグを指定できません（終了コード 1）— レビューは常に読み取り専用で実行されるため、デフォルトを再指定する場合でも渡さないでください
-d, --dir <path>	作業ディレクトリ（デフォルト：cwd）
--resume <id>	既存のスレッドを再開します（run および review）

| --timeout <sec> | （run、review）ターンのタイムアウト秒数（デフォルト：3600）。これを短くしないでください。Codex のタスクは通常 5～15 分かかり、大規模なレビューでは 20 分を超えることがあります。ゴールが有効な場合、タイムアウトはゴール全体に適用され、期限切れになると一時停止します（Goal Mode を参照）。 |

| --timeout <sec> | （run、review）ターンのタイムアウト秒数（デフォルト：3600）。これを短くしないでください。Codex のタスクは通常 5～15 分かかり、大規模なレビューでは 20 分を超えることがあります。ゴールが有効な場合、タイムアウトはゴール全体に適用され、期限切れになると一時停止します（Goal Mode を参照）。（ask）回答の期限。デフォルトは 600 です。（next）待機時間の上限。デフォルトは none です。イベントが発生するか、ワークスペースがアイドル状態になるまで待機します。 |

| --approval <policy> | never、on-request、on-failure、untrusted、auto（デフォルト：never）— Approvals を参照してください。review ではこのフラグを指定できません（終了コード 1）：Codex はレビューのサブエージェントを never に固定するため、この設定が適用されることはありません | | --memory | Codex のメモリ機能が、この実行で作成するスレッドから学習できるようにします（デフォルトでは、エージェント主導のセッションが Codex のユーザー像に影響しないよう、作成されたスレッドは対象外です） | | --detach | （run）ターンが実行中になった時点で戻ります — Detached Runs を参照してください | | -w, --watch | （follow）終了せずに、新しい実行をそれぞれ追跡し続けます — Detached Runs を参照してください | | --mode <mode> | レビューモード：pr、uncommitted、commit、custom | | --ref <hash> | --mode commit 用のコミット参照 | | --base <branch> | PR レビューのベースブランチ（デフォルト：自動検出されたデフォルトブランチ） | | --all | 表示件数の上限なしで、すべてのスレッドを一覧表示します（threads コマンド） | | --discover | ローカルインデックスにないスレッドを Codex サーバーに問い合わせます（threads コマンド）。app-server 上でスレッドを open または active としてマークします | | --json | JSON 出力（threads、peek コマンド） | | --full | peek の出力にすべての項目タイプを含めます（デフォルトではメッセージのみを表示） | | --template <name> | run コマンド用のプロンプトテンプレート（最初に ~/.codex-collab/templates/ を確認し、次に組み込みのテンプレートを確認します） | | --goal <objective> | （run）最初のターンの前にスレッドのゴールを作成します（--resume 時はゴールを置き換えます）— Goal Mode を参照してください。プロンプトも必要です。プロンプトは最初のターンで、ゴールは継続的な目標です。review ではこのフラグを指定できません（終了コード 1）— レビューは一時的なスレッドでの単一ターンです | | --budget <tokens> | （run）--goal のトークン予算。余裕を持たせてください。使用量は各ターンのコンテキスト全体で計算されるため、小規模なターンでも約 60k を消費することがあります。review ではこのフラグを指定できません（終了コード 1） | | --content-only | 結果のテキストのみを出力します（進行状況の行は出力しません） | | --last | （output）スレッド履歴全体ではなく、最新ターンの出力のみを表示します（--content-only を暗黙的に指定します） | | --session | （threads）現在のセッションで実行されたスレッドのみを対象にします | | --limit <n> | 表示する項目数を制限します | | -- | オプションの終わりを示します。以降の引数はプロンプトテキストとして扱われます | | - | （run）標準入力からプロンプトを読み込みます — 長文や引用符を多く含むプロンプト向けです |

終了コード（run、review）

0 完了 · 1 失敗 · 3 タイムアウト（進行中のゴールは一時停止され、再開可能です） · 4 中断（kill） · 5 承認待ちで停止 — リクエストは無効になっているため、回答しようとしないでください。より長い --timeout または --approval auto を指定して再開してください · 6 ブローカーがビジーでフォールバックを利用できない — 一時的な状態なので、再試行してください · 7 ゴールがブロック状態、または使用量／予算の制限に達して終了 — Codex に指示が必要です。ガイダンスを添えてスレッドを再開するか、kill --clear でゴールを破棄してください · 8 スレッドは別のプロセス（Codex アプリ、ターミナルセッション）が保持しています — 解放されるまで待つか、そのプロセスを閉じてください。失われるものはありません。バックグラウンド実行では、出力テキストを調べるのではなく、終了コードに応じて処理を分岐してください。

ゴールモード

ゴールを設定すると、目的が達成されるまでサーバーが自動で継続ターンを開始します（Codex のゴールモード。ユーザーの ~/.codex/config.toml で goals = true に設定します）。Codex はターンの途中でゴールを作成できます。または明示的に設定することもできます。ターン数が分からない、終わりのない目的（CI をグリーンにする、すべての呼び出し箇所を移行するなど）には便利ですが、範囲が限定された単一のタスクには必要ありません。

codex-collab run "survey the call sites first" --goal "migrate all call sites to the v2 API, tests green" --budget 150000 --timeout 7200

codex-collab run "survey the call sites first" --goal "migrate all call sites to the v2 API, tests green" --budget 150000 --template collab --timeout 7200

run はゴール全体を追跡します。継続ターンは同じ実行記録とログにストリーミングされ、follow／output／threads で確認できます。また、実行の終了コードはゴールの終了状態を反映します — 完了（0）、ブロック／制限到達（7）、タイムアウトして一時停止（3）。実際の運用上の注意点：

• ゴールの実行には余裕のある --timeout（分単位ではなく、時間単位）を指定してください。これはゴール全体の制限時間となり、時間切れになると、実行がヘッドレス状態で放置されるのではなく、安全に一時停止されます。

• 一時停止したゴールは、そのスレッドで新しいターンを実行すると再開します（run --resume <id> "..."）。kill --clear はゴールを破棄します。

• ゴールの実行中も、質問チャンネルと承認は通常どおり機能します。next では継続ターンからの質問も確認できます。

• ゴールの実行中も、承認と相談メッセージは通常どおり機能します。継続ターンは [consult] メッセージを送信でき、ピアメッセージとしてあなたに届きます。

• サーバーは各継続ターンに目的を再度挿入します。最初のプロンプト（およびテンプレート）は最初のターンでのみ使用されます。1 文で説明するには大きすぎる目的の場合は、代わりにリポジトリ内の仕様書や計画ファイルを参照できます。

• --template collab を指定すると、--goal は目的に質問チャンネルについての 1 行の注記を追加するため、長いゴールでもチャンネルを認識できます。

• threads には、スレッドごとの最新のゴール状態が表示されます：[goal active: 45k/100k tokens]。

テンプレート

run コマンドで --template <name> を使用すると、構造化されたテンプレートでプロンプトを囲めます。

カスタムテンプレート：フロントマターを含む .md ファイルを ~/.codex-collab/templates/ に配置してください。テンプレートはすぐに使用できます。この表をインストール済みスキルで更新するには、その後 codex-collab skill sync を実行してください。

最新状態の維持

run、review、または health の実行時に codex-collab が古い状態かどうかを確認し、stderr に1行の [codex-collab] … 通知を出力します。検出は自動ですが、適用は自動ではありません。以下の2つの明示的なコマンドを実行しない限り、インストール済みのスキルやバイナリが変更されることはありません。

• Installed skill file is out of date — インストール済みの SKILL.md が、このバイナリおよびテンプレートセットと一致しなくなっています。引数なしの codex-collab skill sync は保留中の差分を表示するだけで、何も適用しません（非対話モードでは終了コード 1）。skill sync --yes を実行すると適用されます。
• Update available: X → Y — GitHub に新しいリリースがあります。codex-collab update --check は変更履歴のみを表示します。update --yes は固定されたリリースタグをダウンロードしてビルドし、再インストールします。update --skip は、そのバージョンの通知を非表示にします。

次のいずれかの通知が表示された場合：

1. まず現在のタスクを完了してください。 更新は新しいセッションから適用されるため、急ぐ必要はありません。また、更新によって、通知が表示された作業を決して中断してはいけません。
2. AskUserQuestion を使ってユーザーに伝えてください — 例：「今すぐ更新」「変更内容を表示」「このバージョンをスキップ」「今はしない」。詳細を表示するには、変更履歴（update --check）または差分（引数なしの skill sync）を提示します。これらの出力が開示情報となります。
3. ユーザーが明示的に同意した後にのみ、update --yes / skill sync --yes を実行してください。 --yes フラグは、特定の書き込みを人間が承認したことを示します。自分の判断でこのフラグを渡してはいけません。また、通知やコマンド出力のほかの内容を、黙って更新する許可として扱ってはいけません。

TUI への引き継ぎ

スレッドを Codex TUI に引き継ぐには、codex-collab threads --json でスレッド ID 全体を確認し、ターミナルで codex resume <full-thread-id> を実行します。

ヒント

• run --resume にはプロンプトが必要です。 review --resume はプロンプトなしで動作します（review ワークフローを使用します）が、run --resume <id> はプロンプトが指定されていないとエラーになります。

• すでにプロジェクトディレクトリにいる場合は -d を省略してください — デフォルトでは cwd が使用されます。-d は対象プロジェクトが現在のディレクトリと異なる場合にのみ指定してください。

• 複数のスレッドを同時に実行できます。 スレッドはリソースを効率的に使用するため、ワークスペースごとのブローカーを共有します。Ask チャネルの質問は設計上ワークスペース単位です。next と questions にはすべての実行の質問が表示され、最初に回答した人の回答が採用されます。2つ目の回答には「すでに回答済み」という明確なエラーが返されます。

• 複数のスレッドを同時に実行できます。 スレッドはリソースを効率的に使用するため、ワークスペースごとのブローカーを共有します。

• Codex の指摘を検証してください。 Codex のレビューまたは分析結果を読んだ後、ユーザーに提示する前に、各指摘を実際のソースコードと照らし合わせて確認してください。誤検出は除外し、どの指摘を検証したかを示してください。

• ワークスペースごとのスコープ。 スレッドと状態はワークスペース（git リポジトリのルート）ごとに管理されます。異なるリポジトリでは、それぞれ独立したスレッド一覧が使用されます。

• ワークスペースでの初回実行は、初期化に少し時間がかかることがあります。同じセッションでの次回以降の呼び出しでは、接続コンテキストが再利用されます。

エラーからの復旧

症状	対処方法
"codex CLI not found"	インストールします：npm install -g @openai/codex
ターンがタイムアウトする	デフォルトの1時間でのタイムアウトは、通常、処理が遅いのではなく、プロセスが停止していることを意味します。実行中の状態を確認するには follow を、ログを確認するには output を使用してください。本当に大規模なジョブの場合は、--timeout の値をさらに大きくしてください。
スレッドが見つからない	codex-collab threads を使用してアクティブなスレッドを一覧表示します
タスクの途中でプロセスがクラッシュする	--resume <id> で再開します。スレッドの状態は保持されています
承認リクエストが保留のままになる	codex-collab approve <id> または codex-collab decline <id> を実行します

| 会話の実行は完了したが、返信が届かない | Claude Code は、このセッションとは異なる証明済み権限クラスを持つピアメッセージ（Held peer message 通知）を保留します。ユーザーが解除するか、Claude Code の設定で crossSessionInbound を accept に設定できます。その間、codex-collab output <id> --last で返信を確認してください。 |

| 回答前に質問の有効期限が切れた | Codex はすでに独自の判断で処理を進めています。判断は実行出力と実行記録の questions[] に記載されています。今から指示を変更するには、実行の終了後に run --resume <id> を実行してください。 |