Codex CLI Integration
Relevant source files
The following files were used as context for generating this wiki page:
The Codex CLI Integration within the Everything Claude Code (ECC) project serves as a bridge to synchronize ECC's specialized agents, prompt roles, and model configurations into a local Codex CLI environment. It enables Claude to coordinate with external models like Codex (OpenAI) and Gemini (Google) using a standardized runtime called ccg-workflow, facilitating multi-model collaborative development workflows such as backend logic analysis, planning, and execution.
Sources: commands/multi-backend.md:10-15, scripts/sync-ecc-to-codex.sh:4-11, CONTRIBUTING.md:200-210
Synchronization and Setup
The integration relies on a synchronization script, scripts/sync-ecc-to-codex.sh, which provisions the user's $HOME/.codex directory with ECC assets. This script ensures that the local Codex environment is aware of ECC's agent definitions and command workflows.
Synchronization Components
| Component | Destination Path | Purpose |
|---|---|---|
| Config | ~/.codex/config.toml | Merges ECC baseline configurations and MCP servers. |
| Agents | ~/.codex/AGENTS.md | Merges ECC agent definitions with user-defined agents using markers. |
| Roles | ~/.codex/agents/*.toml | Syncs ECC specialized agent roles for Codex use. |
| Prompts | ~/.codex/prompts/ | Generates prompt files from ECC commands (e.g., ecc-multi-plan.md). |
| Hooks | Local Git Hooks | Installs global pre-commit and pre-push safety hooks. |
Sources: scripts/sync-ecc-to-codex.sh:18-36, scripts/sync-ecc-to-codex.sh:160-200
Marker-Based Merging
To prevent overwriting user-defined content in AGENTS.md, the integration uses a marker system:
<!-- BEGIN ECC --><!-- END ECC -->
The sync script identifies these markers to replace only the managed section of the file during updates. If markers are missing, the script appends the ECC block to the end of the file.
Sources: scripts/sync-ecc-to-codex.sh:110-140
CCG-Workflow Architecture
The integration utilizes an external runtime called ccg-workflow. This runtime provides the codeagent-wrapper binary, which acts as the execution engine for multi-model calls.
The diagram shows how the Claude Orchestrator uses the codeagent-wrapper to communicate with external Codex and Gemini backends using ECC-defined role prompts.
Sources: commands/multi-backend.md:12-16, commands/multi-workflow.md:11-14
Multi-Model Collaboration
Codex is treated as the primary authority for backend logic, while Gemini serves as the authority for frontend UI/UX design. Claude acts as the central orchestrator, planning, executing, and refactoring prototypes generated by these models.
Trust Hierarchy and Roles
- Codex: Authorized for backend logic, algorithms, and technical feasibility. Role prompts include
analyzer.md,architect.md, andreviewer.mdlocated in~/.claude/.ccg/prompts/codex/. - Gemini: Authorized for frontend UI/UX, responsive layouts, and animations. Role prompts are located in
~/.claude/.ccg/prompts/gemini/. - Claude: Maintains Code Sovereignty. External models have zero filesystem write access. Claude refactors "dirty prototypes" (unified diffs) into production-grade code.
Sources: commands/multi-backend.md:23-28, commands/multi-execute.md:13-17, commands/multi-workflow.md:25-30
Session Persistence
Every call to an external model via codeagent-wrapper returns a SESSION_ID. This ID must be saved and reused in subsequent phases using the resume <SESSION_ID> command. This allows models to maintain context across Research, Ideation, Planning, and Execution phases.
Sources: commands/multi-plan.md:39-42, commands/multi-execute.md:30-40
Implementation Flow
The integration follows a strict 6-phase sequence enforced by commands like /workflow, /backend, and /frontend.
The sequence diagram illustrates the parallel execution of Codex and Gemini during the Ideation, Planning, and Optimization phases, with Claude managing the final implementation.
Sources: commands/multi-workflow.md:70-110, commands/multi-backend.md:55-90
Execution Protocols
| Protocol | Rule |
|---|---|
| Language | Use English for model/tool interaction; user's language for UI. |
| Parallelism | Parallel Codex/Gemini calls MUST use run_in_background: true. |
| Wait Mechanism | Use TaskOutput with a mandatory timeout: 600000 (10 minutes). |
| Validation | Do not proceed to the next phase until the current phase output is validated. |
| Sovereignty | Claude is the ONLY writer. Prototypes from Codex/Gemini are unified diffs only. |
Sources: commands/multi-plan.md:14-25, commands/multi-execute.md:11-20, commands/multi-workflow.md:36-60
Summary
Codex CLI Integration provides the ECC project with multi-model intelligence by syncing specialized ECC roles into the Codex runtime. By utilizing the ccg-workflow wrapper, ECC allows Claude to delegate backend analysis to Codex and frontend design to Gemini while maintaining strict code sovereignty and session-based context persistence. This architecture ensures high-quality planning and execution through parallel multi-model auditing.