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

For AGENTS.md Generation

1. Always run on projects with CLAUDE.md (or let auto-init create it)
2. Validate Codex CLI installed first
3. Keep skills documented with most relevant method (bash vs prompt)
4. Use reference-based approach (no file duplication)

For Codex Execution

1. Use codex exec always (never plain codex in Claude Code)
2. Choose correct model:
   • gpt-5: General reasoning, architecture, analysis
   • gpt-5-codex: Code editing, specialized coding tasks
3. Choose correct sandbox:
   • read-only: Safe analysis (default)
   • workspace-write: File modifications
   • danger-full-access: Network access (rarely needed)
4. Enable search when needed (--search flag)

For Skill Documentation

1. Prompt-only skills: Reference in Codex prompts
2. Functional skills: Execute Python scripts directly
3. Complex skills: Show both methods
4. Always provide working examples

Command Integration

This skill integrates with existing Claude Code commands:

• /init: Auto-generates AGENTS.md after CLAUDE.md creation
• /update-claude: Regenerates AGENTS.md when CLAUDE.md changes
• /check-docs: Validates AGENTS.md exists and is in sync
• /sync-agents-md: Manual AGENTS.md regeneration
• /codex-exec <task>: Wrapper using codex_executor.py

Installation

Prerequisites

1. Codex CLI installed:

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

2. Codex authenticated:

   codex login
   

3. Claude Code v1.0+

Install Skill

Option 1: Copy to project

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

Option 2: Use from this repository

# Skill auto-discovered when Claude Code loads this project

Troubleshooting

Error: "Codex CLI not found"

Solution: Install Codex CLI and ensure it's in PATH

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

Error: "CLAUDE.md not found"

Solution: Skill auto-runs /init with notification. If it fails:

# Manually run /init
/init

Error: "stdout is not a terminal"

Solution: Always use codex exec, never plain codex

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

AGENTS.md Out of Sync

Solution: Regenerate manually

/sync-agents-md

References

• Codex CLI Docs: openai-codex-cli-instructions.md
• Claude Skills Docs: claude-skills-instructions.md
• Example Skills: claude-skills-examples/codex-cli-skill.md
• AGENTS.md Spec: https://agents.md/

Version

v1.0.0 - Initial release (2025-10-30)

License

Apache 2.0

---

Created by: Claude Code Skills Factory Maintained for: Cross-tool team collaboration (Claude Code ↔ Codex CLI) Sync Status: Reference-based bridge (one-way sync: CLAUDE.md → AGENTS.md)