alirezarezvani/claude-code-skill-factory / generated-skills/codex-cli-bridge
codex-cli-bridge
UnverifiedBridge 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
| File | Kind | Size |
|---|---|---|
| CHANGELOG.md | markdown | 5.5 KB |
| HOW_TO_USE.md | markdown | 10.1 KB |
| INSTALL.md | markdown | 10.2 KB |
| README.md | markdown | 9.5 KB |
| SKILL.md | skill md | 8.5 KB |
| agents_md_generator.py | script | 17.4 KB |
| bridge.pyexecutable | script | 7.5 KB |
| claude_parser.py | script | 14.9 KB |
| codex_executor.py | script | 13.0 KB |
| expected_output.json | config | 4.7 KB |
| package.shexecutable | script | 5.8 KB |
| project_analyzer.py | script | 11.0 KB |
| safety_mechanism.py | script | 12.0 KB |
| sample_input.json | config | 1.5 KB |
| skill_documenter.py | script | 9.5 KB |
README.md
View on GitHub# Codex CLI Bridge Skill
**Bridge between Claude Code and OpenAI Codex CLI for seamless cross-tool collaboration**



---
## π― What is This?
The **Codex CLI Bridge** creates seamless interoperability between **Claude Code** and **OpenAI's Codex CLI** by:
1. **Generating AGENTS.md from CLAUDE.md** - Translates Claude Code configuration to Codex CLI format
2. **Documenting Skills for Codex Users** - Shows how to use Claude Skills with Codex CLI
3. **Providing Execution Helpers** - Python wrappers for Codex CLI commands
**The Problem**: Teams using both Claude Code and Codex CLI maintain duplicate documentation and can't easily share skills/workflows.
**The Solution**: This bridge auto-generates AGENTS.md from CLAUDE.md with file references (no duplication), enabling both tools to work with the same project structure.
---
## β¨ Key Features
### 1. Documentation Translation
- β
**CLAUDE.md β AGENTS.md** automatic generation
- β
**Reference-based** (links to files, no duplication)
- β
**One-way sync** (CLAUDE.md is source of truth)
### 2. Skill Documentation
- β
**Functional skills**: Bash execution examples
- β
**Prompt-based skills**: Codex prompt templates
- β
**Most relevant method** per skill type
### 3. Safety Mechanisms
- β
**Auto-checks Codex CLI** installation
- β
**Auto-runs /init** if CLAUDE.md missing
- β
**User-friendly notifications**
### 4. Codex Execution Helpers
- β
**Python wrappers** for Codex CLI commands
- β
**Always uses `codex exec`** (not plain `codex`)
- β
**Intelligent model selection** (gpt-5 vs gpt-5-codex)
- β
**Sandbox mode helpers** (read-only, workspace-write)
---
## π Quick Start
### Prerequisites
```bash
# 1. Codex CLI installed
codex --version # Should show v0.48.0+
# 2. Python 3.7+ with PyYAML
python3 --version
pip3 install PyYAML
# 3. Claude Code project (or auto-create)
```
### Generate AGENTS.md in 3 Steps
```bash
# 1. Navigate to your project
cd /your/claude-code-project
# 2. Run the bridge
python /path/to/codex-cli-bridge/bridge.py
# 3. Done! β
# AGENTS.md created in project root
```
**Output**:
```
================================================================
β
SUCCESS - AGENTS.MD GENERATED
================================================================
π Output: /your/project/AGENTS.md
π Skills documented: 13
π€ Agents documented: 59
Next steps:
1. Review AGENTS.md
2. Test with Codex CLI
3. Share with team (works in both Claude Code and Codex CLI)
```
---
## π¦ What's Included
### Python Modules
| Module | Purpose |
|--------|---------|
| `bridge.py` | Main orchestrator (runs complete workflow) |
| `safety_mechanism.py` | Environment validation (Codex CLI + CLAUDE.md checks) |
| `claude_parser.py` | Parse CLAUDE.md and project structure |
| `project_analyzer.py` | Analyze project metadata and structure |
| `agents_md_generator.py` | Generate AGENTS.md (template-based) |
| `skill_documenter.py` | Document skills for Codex CLI users |
| `codex_executor.py` | Codex CLI execution helpers |
### Documentation
| File | Description |
|------|-------------|
| `SKILL.md` | Complete skill reference |
| `README.md` | This file |
| `HOW_TO_USE.md` | Comprehensive usage guide |
### Templates
| Template | Purpose |
|----------|---------|
| `templates/` | AGENTS.md generation templates (future) |
---
## π Usage Examples
### Example 1: Basic Generation
```bash
# Generate AGENTS.md for current directory
python bridge.py
```
### Example 2: Specific Project
```bash
# Generate for a different project
python bridge.py --project /path/to/other/project
```
### Example 3: Validate Only
```bash
# Check environment without generating
python bridge.py --validate
```
### Example 4: Python API
```python
from bridge import CodexCliBridge
# Create bridge
bridge = CodexCliBridge(project_root="/your/project")
# Run complete workflow
success = bridge.run()
if success:
print("β
AGENTS.md generated successfully")
```
### Example 5: Codex Execution Helper
```python
from codex_executor import CodexExecutor, CodexModel
executor = CodexExecutor()
# Execute analysis task
result = executor.exec_analysis(
prompt="Analyze this codebase for security issues",
model=CodexModel.GPT5
)
print(result.stdout)
```
---
## π How It Works
### Architecture
```
Claude Code Project
βββ CLAUDE.md (Source of truth)
βββ .claude/
β βββ skills/
β βββ agents/
βββ documentation/
β bridge.py
1. Safety Check
βββ Codex CLI installed? β
βββ CLAUDE.md exists? β
(auto-create if missing)
2. Parse & Analyze
βββ Parse CLAUDE.md sections
βββ Scan skills (functional vs prompt-based)
βββ Scan agents
βββ Analyze project structure
3. Generate AGENTS.md
βββ Project overview
βββ Skills documentation (Codex CLI usage)
βββ Workflow patterns (slash commands β Codex)
βββ MCP integration
βββ Command reference
4. Write AGENTS.md
βββ Output: AGENTS.md (reference-based, 19KB example)
Result: Claude Code & Codex CLI Interoperability β
```
---
## π§ Configuration
### Default Behavior
- **Auto-init**: Yes (runs /init if CLAUDE.md missing)
- **Output**: AGENTS.md in project root
- **Approach**: Reference-based (no file duplication)
- **Sync**: One-way (CLAUDE.md β AGENTS.md)
### Customize Behavior
```bash
# Disable auto-init
python bridge.py --no-auto-init
# Show status only
python bridge.py --status
# Validate only (no generation)
python bridge.py --validate
```
---
## π§ͺ Testing
### Test on This Repository
```bash
# Navigate to codex-cli-bridge folder
cd generated-skills/codex-cli-bridge
# Generate AGENTS.md for claude-code-skills-factory
python bridge.py --project ../..
# Check output
cat ../../AGENTS.md
```
**Expected Results**:
- β
AGENTS.md created (19KB, 629 lines)
- β
13 skills documented (8 functional, 5 prompt-based)
- β
59 agents documented
- β
All file references valid
---
## π Troubleshooting
### Common Issues
| Issue | Solution |
|-------|----------|
| "Codex CLI not found" | Install Codex CLI: `which codex` |
| "ModuleNotFoundError: yaml" | Install PyYAML: `pip3 install PyYAML` |
| "CLAUDE.md not found" | Let auto-init create it (default) or run `/init` |
| "stdout is not a terminal" | Use `codex exec` not plain `codex` (skill does this automatically) |
| AGENTS.md out of sync | Regenerate: `python bridge.py` |
### Get Help
```bash
# Show help
python bridge.py --help
# Check status
python bridge.py --status
# Validate environment
python bridge.py --validate
```
See [HOW_TO_USE.md](HOW_TO_USE.md) for comprehensive troubleshooting.
---
## π Documentation
- **[SKILL.md](SKILL.md)** - Complete skill reference
- **[HOW_TO_USE.md](HOW_TO_USE.md)** - Comprehensive usage guide
- **[AGENTS.md](../../AGENTS.md)** - Example output (this repository)
- **[Codex CLI Docs](https://github.com/openai/codex)** - Official Codex documentation
---
## π― Use Cases
### 1. Cross-Tool Teams
**Scenario**: Team uses both Claude Code and Codex CLI
**Solution**:
- Developers using Claude Code maintain CLAUDE.md
- Developers using Codex CLI use AGENTS.md
- Both files reference same skills, agents, documentation
- Bridge keeps AGENTS.md in sync
### 2. Project Migration
**Scenario**: Migrating from Claude Code to Codex CLI (or vice versa)
**Solution**:
- Generate AGENTS.md for existing Claude Code project
- Codex CLI users have instant documentation
- Skills remain usable (Python scripts execute directly)
- Gradual migration possible
### 3. CI/CD Integration
**Scenario**: Auto-sync AGENTS.md when CLAUDE.md changes
**Solution**:
```yaml
# .github/workflows/sync-agents-md.yml
on:
push:
paths: ['CLAUDE.md']
jobs:
sync:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- run: python /path/to/bridge.py
- run: git add AGENTS.md && git commit && git push
```
### 4. Skills Marketplace
**Scenario**: Share Claude Skills with Codex CLI users
**Solution**:
- Include both CLAUDE.md and AGENTS.md in skill package
- Claude Code users: Auto-load from CLAUDE.md
- Codex CLI users: Follow AGENTS.md documentation
- Universal compatibility
---
## π€ Contributing
This skill was created as part of the **Claude Code Skills Factory**.
**Improvements Welcome**:
- Bidirectional sync (AGENTS.md β CLAUDE.md) - planned for v2.0
- Watch mode (auto-regenerate on file changes)
- Additional templates
- More execution helpers
---
## π License
**Apache 2.0**
---
## π Version
**v1.0.0** - Initial Release (2025-10-30)
**Features**:
- β
CLAUDE.md β AGENTS.md generation
- β
Reference-based architecture (no duplication)
- β
Safety mechanisms (Codex CLI + CLAUDE.md checks)
- β
Skill documentation (functional vs prompt-based)
- β
Codex execution helpers
- β
Command reference table
- β
Workflow patterns (Claude β Codex)
**Future (v2.0)**:
- π Bidirectional sync
- π Watch mode
- π Additional templates
- π Plugin integration
---
## π Acknowledgments
- **OpenAI** - Codex CLI
- **Anthropic** - Claude Code
- **Skills Factory** - Comprehensive skill generation templates
---
## π Support
- **Issues**: [GitHub Issues](https://github.com/your-repo/issues)
- **Documentation**: See HOW_TO_USE.md
- **Examples**: See AGENTS.md in this repository
---
**Built with β€οΈ for cross-tool collaboration**
**Claude Code β Codex CLI Bridge v1.0.0**
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 468k | Updated | Claude CodeCodex | Unverified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why β repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" β or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself β your human partner chose inline execution, or no subagent tool is available | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |