codex-collab

codex-collab

Claude Code と OpenAI Codex CLI を協調させてタスクを実行するプラグイン。

概要

このプラグインは、Claude Code と Codex の強みを組み合わせた協調ワークフローを提供します。MCP primary + Bash fallback のデュアルモードアーキテクチャで Codex と通信します。

Codex-Leads（従来のレビュー型）:

• Codex: 計画作成・コードレビュー
• Claude Code: 実装

Claude-Leads（新規）:

• Claude Code: 深い分析・計画作成・レビュー
• Codex: 高速実装（workspace-write sandbox）

インストール

# マーケットプレイスを追加
/plugin marketplace add https://github.com/masuP9/codex-collab

# プラグインをインストール
/plugin install codex-collab@codex-collab

前提条件

• OpenAI Codex CLI (codex) がインストールされていること
• codex exec が動作すること（echo "test" | codex exec -s read-only -）
• 環境変数 OPENAI_API_KEY が設定されていること
• (推奨) Codex MCP サーバー設定済み（codex mcp-server）

アーキテクチャ

Codex CLI との通信は MCP primary + Bash fallback のデュアルモードを採用しています。

MCP モード（推奨）

Codex MCP サーバー (codex mcp-server) 経由でステートフルなセッション管理:

Claude Code → mcp__codex__codex → threadId で会話継続 → mcp__codex__codex-reply

• ステートフル: threadId で会話コンテキスト保持（multi-turn exchange で履歴再構築不要）
• クリーンテキスト: ANSI 除去不要
• ファイル I/O 不要: prompt/output の tmp ファイル不要

Bash モード（フォールバック）

MCP が利用できない場合は codex exec（ステートレス実行）にフォールバック:

Claude Code → Bash tool → codex exec → stdout 取得 → パース

• プロンプトを stdin から渡し、結果を stdout で受け取るシンプルな構造
• 各呼び出しは独立（会話コンテキストはプロンプト内に明示的に含める）
• codex_run_exec() が入出力、ANSI エスケープ除去、exit code ハンドリングを統合処理

モード自動判定

スキル起動時に MCP の可用性を自動プローブし、利用可能なら MCP モード、不可なら Bash モードにフォールバックします。

プロジェクト構造

codex-collab/
├── .claude-plugin/
│   ├── plugin.json            # プラグインメタデータ
│   └── marketplace.json       # マーケットプレイス公開用メタデータ
├── commands/
│   ├── codex-collab.md        # /codex-collab コマンド
│   ├── collab-planning.md     # /collab-planning コマンド
│   ├── strong-inference.md    # /strong-inference コマンド
│   └── devils-advocate.md     # /devils-advocate コマンド
├── hooks/
│   ├── enforce-skill-usage.sh # PreToolUse フック（スキル経由強制）
│   └── enforce-skill-usage.md # フック設定ドキュメント
├── scripts/
│   ├── codex-helpers.sh       # 共通ヘルパー関数
│   └── test-helpers.sh        # ヘルパーのテストスイート
├── docs/
│   └── bash-usage.md          # Bash 使用ルール詳細
└── skills/
    ├── codex-collab/
    │   └── references/        # プロトコル定義・テンプレート
    ├── collab-planning/
    │   └── references/        # 計画テンプレート・レビュー基準
    ├── strong-inference/
    │   └── references/        # 仮説テンプレート
    └── devils-advocate/
        └── references/        # 評価基準・批評テンプレート

ヘルパースクリプト

scripts/codex-helpers.sh には、コマンド間で共有される関数が定義されています:

コア関数（Bash fallback 用の Codex 実行）:

• codex_run_exec() - codex exec のラッパー（stdin パイプ、ANSI 除去、出力保存、exit code ハンドリング）
• codex_build_exec_command() - codex exec コマンド文字列の構築
• codex_write_prompt() - プロンプトを一時ファイルに書き出し
• codex_strip_ansi() - ANSI エスケープコード除去

レビュー解析（Bash fallback 用）:

• codex_run_review() - codex review --uncommitted のラッパー（ANSI 除去、出力保存、モデル retry、exit code ハンドリング）
• codex_infer_verdict() - レビューレスポンスから verdict を推定（メタデータ → [P1]-[P4] → findings なし pass）
• codex_extract_review_findings() - レビューレスポンスから findings を抽出

セッション状態管理（MCP/Bash デュアルモード用）:

• codex_save_session_state() - セッション状態を JSON ファイルに保存（task_id 単位で分離）
• codex_load_session_state() - セッション状態を読み込み（MODE, THREAD_ID 等をグローバル変数にセット）
• codex_save_thread() - 名前付きスレッドを保存（claude-leads の Thread B/C 用）
• codex_load_thread() - 名前付きスレッドを読み込み
• codex_sanitize_task_id() - task_id のファイル名安全化（英数字・ハイフン・アンダースコアのみ）
• codex_json_escape() - JSON 値のエスケープ（引用符・バックスラッシュ・改行）
• codex_diff_tier() - diff のサイズに応じてティア判定（small/medium/large）

メタデータ抽出:

• codex_extract_metadata() - 応答末尾のYAMLブロックを抽出
• codex_get_field() - メタデータフィールド取得
• codex_get_status() - status フィールド取得（continue/stop）
• codex_get_verdict() - verdict フィールド取得（pass/conditional/fail）

ユーティリティ関数:

• codex_ensure_tmp_dir() - 一時ディレクトリ管理
• codex_tmp_path() - 一時ディレクトリ内のファイルパス取得
• codex_hash_content() - クロスプラットフォームハッシュ計算
• codex_generate_signal() - ユニークID生成
• codex_get_language_directive() - 言語指示生成（多言語対応）
• codex_debug() - デバッグログ出力

各コマンドは自動的にヘルパーをsourceします。

使い方

/codex-collab コマンド

協調ワークフローを開始します。計画・実装・レビューの完全サイクル。

/codex-collab 新しい認証機能を実装して

特徴:

• MCP モードではステートフルなセッションで Codex と対話
• Bash フォールバック: codex exec によるステートレス実行
• Codex CLI が未インストールの場合は Claude-only モードにフォールバック

/collab-planning コマンド

Codex と協調して実装計画を作成します。計画のみ — 実装は行いません。

# 基本的な使い方
/collab-planning ユーザーリストAPIにページネーションを追加したい

# イテレーション数指定
/collab-planning --max-iterations 5 認証モジュールのリファクタリング計画

# モード指定
/collab-planning --mode claude-only データベース移行の計画を立てたい

特徴:

• Claude がコンテキスト収集・ドラフト作成、Codex がレビュー・改善提案
• 固定テンプレート出力（目的/スコープ外/WBS/実装手順/リスク/検証/完了条件）
• 品質評価に基づく自動イテレーション（good → 完了、needs-improvement → 改善、major-revision → ユーザー確認）
• 各ラウンド末に要約スナップショット（決定事項/未解決/却下案）で文脈劣化を防止
• 計画ログを tmp/collab-planning/ に保存

/strong-inference コマンド

Strong Inference（強い推論）メソッドを使って、仮説駆動でバグ調査を行います。

# 基本的な使い方
/strong-inference APIが時々500エラーを返す

# モード指定
/strong-inference --mode claude-only テストがフレーキーな原因を調べて