Skip to content

alirezarezvani/claude-code-skill-factory / generated-skills/codex-cli-bridge

codex-cli-bridge

Unverified

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

FileKindSize
CHANGELOG.mdmarkdown5.5 KB
HOW_TO_USE.mdmarkdown10.1 KB
INSTALL.mdmarkdown10.2 KB
README.mdmarkdown9.5 KB
SKILL.mdskill md8.5 KB
agents_md_generator.pyscript17.4 KB
bridge.pyexecutablescript7.5 KB
claude_parser.pyscript14.9 KB
codex_executor.pyscript13.0 KB
expected_output.jsonconfig4.7 KB
package.shexecutablescript5.8 KB
project_analyzer.pyscript11.0 KB
safety_mechanism.pyscript12.0 KB
sample_input.jsonconfig1.5 KB
skill_documenter.pyscript9.5 KB

CHANGELOG.md

View on GitHub
# Changelog

All notable changes to the Codex CLI Bridge skill will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

---

## [1.0.0] - 2025-10-30

### πŸŽ‰ Initial Release

First production-ready release of the Codex CLI Bridge skill.

### Added

#### Core Components
- **bridge.py** - Main orchestrator for complete workflow execution
- **safety_mechanism.py** - Environment validation (Codex CLI + CLAUDE.md checks)
- **claude_parser.py** - CLAUDE.md and project structure parser
- **project_analyzer.py** - Project metadata and structure analysis
- **agents_md_generator.py** - Template-based AGENTS.md generation
- **skill_documenter.py** - Skill documentation for Codex CLI users
- **codex_executor.py** - Codex CLI execution helpers with Python wrappers

#### Safety Features
- Auto-check Codex CLI installation
- Auto-run `/init` if CLAUDE.md missing (with user notification)
- Comprehensive environment validation
- User-friendly error messages
- Status reporting

#### Documentation
- **README.md** - Complete skill overview with quick start guide
- **HOW_TO_USE.md** - Comprehensive usage guide with examples
- **SKILL.md** - Full skill reference documentation
- **sample_input.json** - Example input structure
- **expected_output.json** - Example output format

#### Slash Commands
- **`/sync-agents-md`** - Regenerate AGENTS.md from CLAUDE.md
- **`/codex-exec`** - Execute Codex CLI commands with proper syntax

#### Key Features
- βœ… CLAUDE.md β†’ AGENTS.md automatic generation
- βœ… Reference-based architecture (no file duplication)
- βœ… Intelligent skill documentation (functional vs prompt-based)
- βœ… Codex execution helpers (always uses `codex exec`)
- βœ… Model selection logic (gpt-5 vs gpt-5-codex)
- βœ… Sandbox mode helpers (read-only, workspace-write)
- βœ… Session management (start, resume)
- βœ… Workflow pattern translation (Claude Code β†’ Codex CLI)
- βœ… Command reference table
- βœ… MCP integration documentation

### Technical Details

- **Language**: Python 3.7+
- **Dependencies**: PyYAML
- **File Size**: 114KB (complete package)
- **Modules**: 7 Python files
- **Documentation**: 4 comprehensive guides
- **Tested On**: claude-code-skills-factory repository (13 skills, 59 agents)

### Statistics

- **Lines of Code**: ~2,500
- **Documentation**: ~3,000 lines
- **Test Coverage**: Manual testing on real project
- **Generated Output**: 19KB AGENTS.md (629 lines)

### Architecture Decisions

- **One-way sync**: CLAUDE.md β†’ AGENTS.md (bidirectional deferred to v2.0)
- **Reference-based**: All file paths, no content duplication
- **Safety-first**: Auto-validation before any operation
- **Template-driven**: Consistent output format

### Known Limitations

- Bidirectional sync (AGENTS.md β†’ CLAUDE.md) not implemented (planned for v2.0)
- Watch mode for auto-regeneration not included
- MCP server detection requires manual configuration
- Templates folder created but no custom templates yet

---

## [Unreleased] - Future Versions

### Planned for v2.0

#### Major Features
- πŸ”„ **Bidirectional Sync**: AGENTS.md β†’ CLAUDE.md updates
  - Conflict resolution
  - Merge strategies
  - Change detection

- πŸ”„ **Watch Mode**: Auto-regenerate on file changes
  - File system monitoring
  - Debounced updates
  - Background process

- πŸ”„ **Enhanced Templates**: Customizable AGENTS.md output
  - Multiple template formats
  - User-defined sections
  - Style customization

#### Improvements
- **Performance**: Caching for faster re-generation
- **Validation**: Enhanced YAML and Markdown validation
- **Testing**: Automated test suite
- **Logging**: Structured logging system
- **CLI**: Enhanced command-line interface

#### New Features
- **Plugin System**: Extend functionality with plugins
- **Multiple Formats**: Generate docs in different formats (HTML, PDF)
- **Diff View**: Show changes between versions
- **Analytics**: Track skill usage and popularity

### Planned for v1.1 (Minor Updates)

- **Bug Fixes**: Address any issues reported by users
- **Documentation**: Add more examples and use cases
- **Error Handling**: More granular error messages
- **Performance**: Optimize parsing for large projects

---

## Version History

| Version | Date | Description |
|---------|------|-------------|
| 1.0.0 | 2025-10-30 | Initial production release |

---

## Migration Guide

### From Nothing to v1.0.0

**New Installation**:
```bash
# 1. Clone or copy the skill
cp -r codex-cli-bridge ~/.claude/skills/

# 2. Install dependencies
pip3 install PyYAML

# 3. Validate installation
python3 ~/.claude/skills/codex-cli-bridge/bridge.py --validate

# 4. Generate AGENTS.md
python3 ~/.claude/skills/codex-cli-bridge/bridge.py
```

---

## Breaking Changes

### None (Initial Release)

Future versions will document breaking changes here.

---

## Deprecations

### None (Initial Release)

Future versions will document deprecations here.

---

## Security Updates

### None (Initial Release)

Security updates will be documented here in future versions.

---

## Contributors

- **Claude Code Skills Factory Team**
- Built with ❀️ for cross-tool collaboration

---

## Links

- [GitHub Repository](https://github.com/your-repo/codex-cli-bridge)
- [Documentation](./HOW_TO_USE.md)
- [Bug Reports](https://github.com/your-repo/issues)
- [Feature Requests](https://github.com/your-repo/issues)

---

**Legend**:
- βœ… Implemented
- πŸ”„ Planned
- πŸ› Bug Fix
- πŸŽ‰ Major Feature
- πŸ“š Documentation
- ⚑ Performance
- πŸ”’ Security

---

*Last Updated: 2025-10-30*
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: 470kUpdated Claude CodeCodexVerifiedInstall
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: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 322kUpdated Claude CodeCodexVerifiedInstall