codex-cli-bridge

Codex CLI Bridge Skill

目的

このスキルは、Claude Code と OpenAI's Codex CLI の間に包括的なブリッジを構築し、以下を通じてシームレスな相互運用を可能にします。

1. ドキュメントの変換：CLAUDE.md → AGENTS.md に変換します（参照ベースで、ファイルを複製しません）
2. 実行ヘルパー：Codex CLI コマンド用の Python ラッパーです（常に codex exec を使用します）
3. スキルのドキュメント化：Claude Skills を Codex CLI ユーザーが利用できるようにします

主な機能

1. CLAUDE.md → AGENTS.md の生成

• CLAUDE.md とプロジェクト構造を解析します
• .claude/skills/、.claude/agents/、documentation/ フォルダーをスキャンします
• ファイルパス参照を含む包括的な AGENTS.md を生成します
• 参照ベース：ファイルは複製せず、既存のファイルへのリンクのみを使用します
• 最も関連性の高い利用方法（bash スクリプトまたはプロンプト参照）でスキルをドキュメント化します

2. 安全機構

• Codex CLI のインストールを自動確認します（codex --version）
• CLAUDE.md がない場合は /init を自動実行します（ユーザーに通知します）
• 認証と環境を検証します
• ユーザーフレンドリーなエラーメッセージを表示します

3. Codex CLI 実行ヘルパー

• exec_analysis() - 読み取り専用の分析タスク（gpt-5、読み取り専用サンドボックス）
• exec_edit() - コード編集タスク（gpt-5-codex、ワークスペースへの書き込み）
• exec_with_search() - ウェブ検索を有効にしたタスク
• resume_session() - 最後の Codex セッションを続行します
• 常に codex exec を使用します（通常の codex は使用しません。Claude Code では重要です）

4. Codex CLI 向けのスキルのドキュメント化

• プロンプト専用スキル：Codex プロンプトで参照する方法を示します
• 機能を備えたスキル：Python スクリプトを直接実行する方法を示します
• 複雑なスキル：両方の方法を示します
• 適切な codex exec コマンド構文を含みます
• モデルの選択方法を案内します（gpt-5 と gpt-5-codex）

入力要件

AGENTS.md の生成

{
  "action": "generate-agents-md",
  "project_root": "/path/to/project",
  "options": {
    "validate_codex": true,
    "auto_init": true,
    "include_mcp": true,
    "skill_detail_level": "relevant"
  }
}

Codex の実行

{
  "action": "codex-exec",
  "task_type": "analysis|edit|search",
  "prompt": "Your task description",
  "model": "gpt-5|gpt-5-codex",
  "sandbox": "read-only|workspace-write|danger-full-access"
}

出力形式

AGENTS.md の構成

# AGENTS.md

## Project Overview
[From CLAUDE.md]

## Available Skills
### Skill Name
**Location**: `path/to/skill/`
**Using from Codex CLI**: [Most relevant method]

## Workflow Patterns
[Slash commands → Codex equivalents]

## MCP Integration
[MCP server references]

## Command Reference
| Claude Code | Codex CLI |
|-------------|-----------|
[Mappings]

実行ヘルパーの出力

{
  "status": "success|error",
  "output": "Command output",
  "session_id": "uuid",
  "model_used": "gpt-5|gpt-5-codex",
  "command": "codex exec ..."
}

Python スクリプト

safety_mechanism.py

• Codex CLI のインストールを確認します
• CLAUDE.md があることを検証します（ない場合は /init を自動実行します）
• 環境を検証します
• ユーザーに通知します

claude_parser.py

• CLAUDE.md のセクションを解析します
• スキル、エージェント、コマンドをスキャンします
• 品質ゲートと MCP の設定を抽出します
• ファイルパスのみを返します（コンテンツを複製しません）

project_analyzer.py

• プロジェクト構造を自動検出します
• Claude Code のすべてのアセットを検出します
• プロジェクトのメタデータを生成します
• 参照マップを構築します

agents_md_generator.py

• テンプレートベースで AGENTS.md を生成します
• ファイルパスを参照します（複製しません）
• スキルをドキュメント化します（最も関連性の高い方法を使用）
• ワークフローを変換します（Claude → Codex）

skill_documenter.py

• Codex CLI ユーザー向けにスキルをドキュメント化します
• スキルの種類ごとに最も関連性の高い利用方法を判断します
• Python スクリプトの bash 実行例を生成します
• Codex プロンプトのテンプレートを作成します

codex_executor.py

• Codex CLI コマンド用の Python ラッパーです
• モデルをインテリジェントに選択します（gpt-5 と gpt-5-codex）
• サンドボックスモード用のヘルパーを提供します
• セッションを管理します
• 常に codex exec を使用します

使用例

例 1：AGENTS.md を生成する

ユーザーのプロンプト：

Generate AGENTS.md for this project

実行内容：

1. 安全機構が Codex CLI のインストールを確認します
2. CLAUDE.md があることを確認します（ない場合は /init を自動実行します）
3. CLAUDE.md とプロジェクト構造を解析します
4. ファイル参照を含む AGENTS.md を生成します
5. すべてのスキルを、最も関連性の高い利用方法でドキュメント化します

出力：プロジェクトのルートにある完全な AGENTS.md ファイル

---

例 2：Codex の分析タスクを実行する

ユーザーのプロンプト：

Use Codex to analyze this codebase for security vulnerabilities

実行内容：

from codex_executor import CodexExecutor

executor = CodexExecutor()
result = executor.exec_analysis(
    "Analyze this codebase for security vulnerabilities",
    model="gpt-5"
)

実行コマンド：

codex exec -m gpt-5 -s read-only \
  -c model_reasoning_effort=high \
  "Analyze this codebase for security vulnerabilities"

---

例 3：Codex でコード編集を実行する

ユーザーのプロンプト：

Use Codex to refactor main.py for better async patterns

実行内容：

executor = CodexExecutor()
result = executor.exec_edit(
    "Refactor main.py for better async patterns",
    model="gpt-5-codex"
)

実行コマンド：

codex exec -m gpt-5-codex -s workspace-write \
  -c model_reasoning_effort=high \
  "Refactor main.py for better async patterns"

---

例 4：Codex セッションを再開する

ユーザーのプロンプト：

Continue the previous Codex session

実行内容：

executor = CodexExecutor()
result = executor.resume_session()

実行コマンド：

codex exec resume --last

ベストプラクティス

AGENTS.md の生成

1. CLAUDE.md があるプロジェクトでは必ず実行してください（または自動初期化で作成してください）
2. 最初に Codex CLI がインストールされていることを確認してください
3. スキルは、最も関連性の高い方法（bash とプロンプト）で文書化してください
4. 参照ベースのアプローチを使用してください（ファイルを複製しないでください）

Codex の実行

1. 常に codex exec を使用してください（Claude Code では通常の codex を使用しないでください）
2. 適切なモデルを選択してください：
   • gpt-5：一般的な推論、アーキテクチャ、分析
   • gpt-5-codex：コード編集、専門的なコーディングタスク
3. 適切なサンドボックスを選択してください：
   • read-only：安全な分析（デフォルト）
   • workspace-write：ファイルの変更
   • danger-full-access：ネットワークアクセス（ほとんど必要ありません）
4. 必要に応じて検索を有効にしてください（--search フラグ）

スキルのドキュメント化

1. プロンプトのみのスキル：Codex のプロンプトで参照してください
2. 機能を持つスキル：Python スクリプトを直接実行してください
3. 複雑なスキル：両方の方法を示してください
4. 必ず動作する例を提示してください

コマンドとの統合

このスキルは、既存の Claude Code コマンドと統合されます：

• /init：CLAUDE.md の作成後に AGENTS.md を自動生成します
• /update-claude：CLAUDE.md が変更されたときに AGENTS.md を再生成します
• /check-docs：AGENTS.md が存在し、同期されていることを確認します
• /sync-agents-md：AGENTS.md を手動で再生成します
• /codex-exec <task>：codex_executor.py を使用するラッパーです

インストール

前提条件

1. Codex CLI がインストールされていること：

   codex --version  # Should show v0.48.0 or higher
   

2. Codex の認証が完了していること：

   codex login
   

3. Claude Code v1.0 以降

スキルのインストール

オプション 1：プロジェクトにコピー

cp -r generated-skills/codex-cli-bridge ~/.claude/skills/

オプション 2：このリポジトリから使用

# Skill auto-discovered when Claude Code loads this project

トラブルシューティング

エラー：「Codex CLI が見つかりません」

解決方法：Codex CLI をインストールし、PATH に含まれていることを確認してください

which codex  # Should return path
codex --version  # Should work

エラー：「CLAUDE.md が見つかりません」

解決方法：このスキルは通知を表示して /init を自動実行します。失敗した場合：

# Manually run /init
/init

エラー：「stdout はターミナルではありません」

解決方法：必ず codex exec を使用し、通常の codex は使用しないでください

❌ codex -m gpt-5 "task"
✅ codex exec -m gpt-5 "task"

AGENTS.md が同期されていない場合

解決方法：手動で再生成してください

/sync-agents-md

参考資料

• Codex CLI ドキュメント：openai-codex-cli-instructions.md
• Claude Skills ドキュメント：claude-skills-instructions.md
• スキルの例：claude-skills-examples/codex-cli-skill.md
• AGENTS.md の仕様：https://agents.md/

バージョン

v1.0.0 - 初回リリース（2025-10-30）

ライセンス

Apache 2.0

---

作成者：Claude Code Skills Factory メンテナンス対象：ツール間のチームコラボレーション（Claude Code ↔ Codex CLI） 同期ステータス：参照ベースのブリッジ（片方向の同期：CLAUDE.md → AGENTS.md）