Codex CLI Bridge

Codex CLI Bridge Skill

Purpose

This skill creates a comprehensive bridge between Claude Code and OpenAI's Codex CLI, enabling seamless interoperability through:

1. Documentation Translation: Converts CLAUDE.md → AGENTS.md (reference-based, no file duplication)
2. Execution Helpers: Python wrappers for Codex CLI commands (always uses codex exec)
3. Skill Documentation: Makes Claude Skills accessible to Codex CLI users

Key Capabilities

1. CLAUDE.md → AGENTS.md Generation

• Parses CLAUDE.md and project structure
• Scans .claude/skills/, .claude/agents/, documentation/ folders
• Generates comprehensive AGENTS.md with file path references
• Reference-based: No file duplication, only links to existing files
• Documents Skills with most relevant usage method (bash scripts vs prompt references)

2. Safety Mechanism

• Auto-checks Codex CLI installation (codex --version)
• Auto-runs /init if CLAUDE.md missing (with user notification)
• Validates authentication and environment
• User-friendly error messages

3. Codex CLI Execution Helpers

• exec_analysis() - Read-only analysis tasks (gpt-5, read-only sandbox)
• exec_edit() - Code editing tasks (gpt-5-codex, workspace-write)
• exec_with_search() - Web search-enabled tasks
• resume_session() - Continue last Codex session
• Always uses codex exec (never plain codex - critical for Claude Code)

4. Skill Documentation for Codex CLI

• Prompt-only skills: Show how to reference in Codex prompts
• Functional skills: Show how to execute Python scripts directly
• Complex skills: Show both methods
• Includes proper codex exec command syntax
• Model selection guidance (gpt-5 vs gpt-5-codex)

Input Requirements

For AGENTS.md Generation

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

For Codex Execution

{
  "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"
}

Output Formats

AGENTS.md Structure

# 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]

Execution Helper Output

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

Python Scripts

safety_mechanism.py

• Check Codex CLI installation
• Validate CLAUDE.md exists (auto-run /init if missing)
• Environment validation
• User notifications

claude_parser.py

• Parse CLAUDE.md sections
• Scan skills, agents, commands
• Extract quality gates and MCP configuration
• Return file paths only (no content duplication)

project_analyzer.py

• Auto-detect project structure
• Discover all Claude Code assets
• Generate project metadata
• Build reference map

agents_md_generator.py

• Template-based AGENTS.md generation
• File path references (no duplication)
• Skill documentation (most relevant method)
• Workflow translation (Claude → Codex)

skill_documenter.py

• Document skills for Codex CLI users
• Determine most relevant usage method per skill type
• Generate bash examples for Python scripts
• Create Codex prompt templates

codex_executor.py

• Python wrappers for Codex CLI commands
• Intelligent model selection (gpt-5 vs gpt-5-codex)
• Sandbox mode helpers
• Session management
• Always uses codex exec

Usage Examples

Example 1: Generate AGENTS.md

User prompt:

Generate AGENTS.md for this project

What happens:

1. Safety mechanism checks Codex CLI installed
2. Checks CLAUDE.md exists (auto-runs /init if missing)
3. Parses CLAUDE.md and project structure
4. Generates AGENTS.md with file references
5. Documents all skills with most relevant usage method

Output: Complete AGENTS.md file in project root

Example 2: Execute Codex Analysis Task

User prompt:

Use Codex to analyze this codebase for security vulnerabilities

What happens:

from codex_executor import CodexExecutor

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

Executes:

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

Example 3: Execute Codex Code Editing

User prompt:

Use Codex to refactor main.py for better async patterns

What happens:

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

Executes:

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

Example 4: Resume Codex Session

User prompt:

Continue the previous Codex session

What happens:

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

Executes:

codex exec resume --last

Best Practices