codex-subagents

Codex Subagents

概要

codex-subagent はバックグラウンドスレッドに作業を委任し、メインコンテキストを軽量に保ちます。スレッドはデフォルトでデタッチ状態で実行されます。結果を確認するには wait／peek を使用してください。

重要なルール：

1. 実行中のスレッドには送信できません。後続のメッセージを送る前に、必ず待機してください。
2. --permissions read-only または --permissions workspace-write を使用してください（workspace-read は使用しないでください）。

詳しいワークフロードキュメントについては、reference/workflow.md を参照してください。

使用する場面

状況	サブエージェントが役立つ理由
並列での調査タスク	複数のスレッドを同時に実行できます
コンテキストが肥大化する場合	調査を別のスレッドに分離できます
実行に時間がかかる作業	デタッチして実行し、後で確認できます

使用しない場面：簡単なインラインの質問、現在の状態に密接に依存する作業。

基本的なワークフロー

1. start with --prompt    (inline text or stdin)
2. wait/peek → check result
3. send → resume with follow-up (ONLY after thread stops)
4. archive/clean → lifecycle management

実行中のスレッドに関するルール

実行中のスレッドには送信できません。 これは最もよくある間違いです。

# WRONG - thread might still be running
echo "followup" | codex-subagent send thread-abc --prompt -

# RIGHT - wait first, then send
codex-subagent wait --threads thread-abc
echo "followup" | codex-subagent send thread-abc --prompt -

再開可能なステータス：completed、failed、stopped、waiting

クイックリファレンス

コマンド	目的	主なフラグ
start	新しいスレッドを起動する	--role、--permissions、--prompt、--label、-w
send	停止したスレッドを再開する	<thread-id>、--prompt、-w
peek	未確認の最新メッセージを読む	<thread-id>、--save-response
log	全履歴を表示する	<thread-id>、--tail、--json
status	スレッドの概要を表示する	<thread-id>
wait	スレッドが停止するまで待機する	--threads、--labels、--all、--follow-last
list	スレッドを表示する	--status、--label、--role
archive	完了したスレッドをアーカイブに移動する	--completed、--yes、--dry-run
clean	古いアーカイブを削除する	--older-than-days、--yes

プロンプト入力：簡単なプロンプトには --prompt "text" を使用します。--prompt - は標準入力から読み込みます（複数行の場合）。ファイルには -f／--prompt-file を使用します。

位置引数のスレッド ID：peek abc123 は peek -t abc123 と同じように機能します。

よく使うパターン

シンプルなインラインプロンプト

codex-subagent start --role researcher --permissions read-only \
  --label "quick-task" --prompt "List all exported functions in src/lib/"

複数行プロンプト（heredoc）

cat <<'EOF' | codex-subagent start --role researcher --permissions read-only --label "auth-research" --prompt -
Research authentication patterns in this codebase:
1. Find all auth-related files
2. Document the auth flow
3. Note any security concerns
EOF

並列調査

# Launch multiple researchers
cat <<'EOF' | codex-subagent start --role researcher --permissions read-only --label "API: Stripe" --prompt -
Research Stripe API authentication methods and best practices
EOF

cat <<'EOF' | codex-subagent start --role researcher --permissions read-only --label "API: Twilio" --prompt -
Research Twilio API authentication methods and best practices
EOF

# Wait for all, see results
codex-subagent wait --labels "API:" --follow-last

ブロッキングタスク

# -w blocks until complete (may take minutes)
cat <<'EOF' | codex-subagent start --role researcher --permissions read-only --prompt - -w --save-response result.txt
Analyze error handling patterns in src/
EOF
cat result.txt

警告：-w はエージェントの実行中、待機し続けます。時間のかかるタスクには、デタッチモードで実行して wait --follow-last を使う方法をおすすめします。

古い作業をクリーンアップする

# Two-phase: archive completed, then clean old archives
codex-subagent archive --completed --yes
codex-subagent clean --older-than-days 30 --yes

トラブルシューティング

問題	原因	解決方法
"profile does not exist"	権限が間違っています	read-only または workspace-write を使用してください（workspace-read は使用しないでください）
"not resumable" エラー	スレッドがまだ実行中です	まず wait を実行し、その後 send を実行してください
"different controller"	セッションが間違っています	--controller-id を使用するか、list を確認してください
スレッドが見つからない	アーカイブされています	アーカイブディレクトリを確認するか、タスクを再実行してください

チェックリスト

• start に --role、--permissions、--prompt、--label が指定されている
• 権限が read-only または workspace-write になっている
• send の前に wait を実行している（実行中のスレッドには絶対に送信しない）
• --save-response または peek で結果を取得している