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
```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)