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:

   bash

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

2. •

   Codex authenticated:

   bash

   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)