ccx is a powerful Rust CLI tool for seamlessly converting configuration files between Claude Code and OpenAI Codex formats. It ensures the integrity of data with detailed conversion reports, prohibiting silent data loss, and providing users with a robust solution for managing their coding environments.
ccx is a versatile command-line interface (CLI) application developed in Rust, designed to facilitate the bidirectional conversion of configuration files between Claude Code and OpenAI Codex CLI. This tool supports various configuration types, including Skills, Plugins, Hooks, MCP servers, Memory files, Subagents, and Settings, utilizing a robust mapping system defined in mappings/*.yaml with 304 entries.
Key Features
- Bidirectional Conversion: Effortlessly convert files between Claude Code (
.claude/, JSON) and Codex CLI (.codex/, TOML). - Comprehensive Coverage: Supports multiple configuration modalities, ensuring exhaustive transformation capabilities.
- Conversion Reporting: Each conversion run generates a detailed report categorizing the results into lossless, lossy, degraded, and dropped entries, thus preventing silent data loss.
Claude Code .claude/ (JSON) ⇄ Codex CLI .codex/ (TOML)
Usage Examples
The CLI supports various operations with easy-to-understand commands:
# Convert a Claude skill to Codex format
ccx c2x .claude/skills/deploy/SKILL.md
# Convert Codex config.toml to Claude format, report only
ccx x2c .codex/config.toml --dry-run --report
# Diagnose an MCP configuration before conversion
ccx check .mcp.json
# Fail CI if any fields are dropped
ccx c2x .claude/skills/deploy/SKILL.md --strict
# Generate a machine-readable JSON report
ccx c2x .mcp.json --dry-run --report=json
Conversion Report Interpretation
Upon completion of a conversion, a summary report is provided, detailing the success and failure of various components within the configuration, helping users understand the transformation impact. Here's a sample report structure:
✔ skills/deploy/SKILL.md → .agents/skills/deploy/SKILL.md
◎ name, description lossless
○ when_to_use → description(concatenated) lossy
...
Summary: 2 lossless, 3 lossy (2 degraded), 2 dropped, 1 body-warning
Symbols Used in Reports
| Symbol | Meaning |
|---|---|
| ◎ | Lossless — fully equivalent |
| ○ | Lossy — partially preserved information |
| △ | Degraded — moved to a broader scope |
| ✕ | Dropped — no conversion target; discarded |
| ⚠ | Body warning — requires manual review |
Documentation
For a deeper understanding of implementation and configuration details, refer to the following resources:
- Full Design Specification - In-depth documentation on design choices, transformation processes, and CLI features.
- Mapping Tables - A detailed look at conversion mappings, structured to enhance the conversion experience.
No comments yet.
Sign in to be the first to comment.