Skip to main content
skill CX Codex

codex-cli-bridge — Claude Code skill: features and installation

The codex-cli-bridge skill connects Claude Code projects with Codex CLI by creating AGENTS.md from CLAUDE.md and providing helpers to run Codex tasks. Use it when both tools are part of your workflow.

MIT ★ 907 updated 2025-11-12

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add alirezarezvani/claude-code-skill-factory --skill codex-cli-bridge -a claude-code
Open on GitHub

What codex-cli-bridge does

The skill reads CLAUDE.md alongside the project layout, then builds an AGENTS.md that points to existing files. It scans .claude/skills/, .claude/agents/, and documentation/, explains how Codex users can work with the project’s skills, and maps Claude Code workflows to Codex commands. It references files rather than copying their contents.

Python wrappers handle Codex analysis in read-only mode, edits with workspace-write, web search, and resuming the latest session. They invoke codex exec; analysis uses gpt-5, while code changes use gpt-5-codex. The skill checks that Codex CLI is installed and authenticated. Codex CLI must be available before its task helpers can run.

When CLAUDE.md is missing, the skill can run /init and notify the user. It also checks the environment before generating AGENTS.md, whose project documentation uses file-path references instead of duplicated content.

What it helps with

  • Generate AGENTS.md from CLAUDE.md
  • Document Claude Code skills for Codex CLI users
  • Run a read-only codebase analysis through Codex
  • Send code editing tasks to Codex
  • Resume the latest Codex session

Example prompts for the agent

  • Create an AGENTS.md for this project based on CLAUDE.md.
  • Ask Codex to inspect this codebase for security issues in read-only mode.
  • Resume the latest Codex session.

How to install codex-cli-bridge

1Skills CLI (Vercel)

npx skills add alirezarezvani/claude-code-skill-factory --skill codex-cli-bridge -a claude-code

2Manually: put the files in place

~/.claude/skills/codex-cli-bridge/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/codex-cli-bridge/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about codex-cli-bridge

How do I install codex-cli-bridge in Claude Code?

Run npx skills add alirezarezvani/claude-code-skill-factory --skill codex-cli-bridge -a claude-code. The skill file is at ~/.claude/skills/codex-cli-bridge/SKILL.md.

What does codex-cli-bridge do?

It creates an AGENTS.md with references to project files and provides Python wrappers for Codex CLI analysis, edits, web search, and session resumption.

What do I need to run Codex tasks with this skill?

Codex CLI must be installed and authenticated; the skill checks both. If the project lacks CLAUDE.md, it can run /init.

Source text

SKILL.md · MIT
---
name: codex-cli-bridge
description: Bridge between Claude Code and OpenAI Codex CLI - generates AGENTS.md from CLAUDE.md, provides Codex CLI execution helpers, and enables seamless interoperability between both tools
---

# 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
```json
{
  "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
```json
{
  "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
```markdown
# 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
```python
{
  "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**:
```python
from codex_executor import CodexExecutor

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

**Executes**:
```bash
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**:
```python
executor = CodexExecutor()
result = executor.exec_edit(
    "Refactor main.py for better async patterns",
    model="gpt-5-codex"
)
```

**Executes**:
```bash
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**:
```python
executor = CodexExecutor()
result = executor.resume_session()
```

**Executes**:
```bash
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**
```bash
cp -r generated-skills/codex-cli-bridge ~/.claude/skills/
```

**Option 2: Use from this repository**
```bash
# 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
```bash
which codex  # Should return path
codex --version  # Should work
```

### Error: "CLAUDE.md not found"
**Solution**: Skill auto-runs `/init` with notification. If it fails:
```bash
# Manually run /init
/init
```

### Error: "stdout is not a terminal"
**Solution**: Always use `codex exec`, never plain `codex`
```bash
❌ codex -m gpt-5 "task"
✅ codex exec -m gpt-5 "task"
```

### AGENTS.md Out of Sync
**Solution**: Regenerate manually
```bash
/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)

© alirezarezvani · MIT · alirezarezvani/claude-code-skill-factory

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set36

The whole set →
agent-factory agent-factory generates production-ready Claude Code sub-agent files with YAML frontmatter, tool permissions, and MCP server integrations. CX Codex +1 ★ 907repo stars content-trend-researcher content-trend-researcher studies topic signals and audience intent across content platforms, then builds article outlines. Use it to validate ideas and spot underserved subjects. CX Codex +1 ★ 907repo stars sync-agents-md sync-agents-md rebuilds AGENTS.md from CLAUDE.md so the Claude CLI docs in a repo follow the project config. Handy after config edits or a new skill. CX Codex +1 ★ 907repo stars skills-guide Guides you through a quick questionnaire to build and package multi-file Claude skills with YAML frontmatter, Python code, and docs. CX Codex ★ 907repo stars prompts-guide prompts-guide — a subagent that helps build prompts for any model via prompt-factory skill: pick from 69 presets or build a custom one through 5–7 questions. CX Codex ★ 907repo stars codex-exec codex-exec runs Codex CLI tasks directly inside Claude Code sessions. It applies proper sandboxing modes, reasoning flags, and selects between GPT-5 models. CX Codex +1 ★ 907repo stars hooks-guide The hooks-guide subagent walks you through designing a Claude Code hook, from its trigger event to its action. Use it to turn a workflow automation idea into hook files. CX Codex ★ 907repo stars ms365-tenant-manager ms365-tenant-manager — a skill for Microsoft 365 Global Administrators: tenant setup, user management, security policies, and PowerShell automation. CX Codex +1 ★ 907repo stars

Project sponsors

Companies that keep this analytics open