# How to Configure claude-code-harness to Integrate with Codex CLI Instead of Claude Code > Integrate claude-code-harness with Codex CLI. Follow simple steps to install Codex CLI and add the codex flag to delegate tasks, bypassing Claude Code for enhanced functionality. - Repository: [Chachamaru/claude-code-harness](https://github.com/Chachamaru127/claude-code-harness) - Tags: how-to-guide - Published: 2026-05-28 --- **To configure claude-code-harness for Codex CLI integration, install the Codex CLI using [`./scripts/setup-codex.sh`](https://github.com/Chachamaru127/claude-code-harness/blob/main/./scripts/setup-codex.sh), then add the `--codex` flag to any harness command to delegate tasks to the Codex CLI instead of Claude Code.** The **claude-code-harness** repository supports dual execution modes: the native Claude Code engine or the external **Codex CLI**. Because the harness treats Codex as an *internal-compatible* tool requiring explicit opt-in, you must enable it manually before delegation. This guide covers the complete setup process, from CLI installation to task execution, based on the actual source implementation in `Chachamaru127/claude-code-harness`. ## Install the Codex CLI Before the harness can delegate work, you must install the Codex CLI binary (version ≥ 0.134.0) and configure your environment. Run the official setup script from the repository root: ```bash ./scripts/setup-codex.sh ``` This script performs four critical actions: - **Node.js validation** – Ensures a compatible runtime exists before installation. - **Global npm install** – Executes `npm i -g @openai/codex@0.134.0` (or the repository's pinned version). - **PATH configuration** – Adds `$HOME/.codex/bin` to your shell PATH. - **Version verification** – Runs `codex --version` to confirm the minimum required version is present. The script also writes Codex-specific configuration files under `${CODEX_HOME:-~/.codex}`, mirroring how Claude Code stores its [`AGENTS.md`](https://github.com/Chachamaru127/claude-code-harness/blob/main/AGENTS.md) file. These files live in your local Codex workspace and remain unversioned to prevent repository pollution. ## Enable Codex CLI Support in the Harness Once the CLI is installed, explicitly tell the harness to recognize the Codex toolchain. You have two equivalent methods: **Method 1: Skill-based setup (recommended)** Execute the built-in skill from within the harness interface: ```bash /harness-setup codex ``` This invokes the same logic as the shell script but integrates with the harness UI. The skill definition resides in [`skills/harness-setup/SKILL.md`](https://github.com/Chachamaru127/claude-code-harness/blob/main/skills/harness-setup/SKILL.md). **Method 2: Manual execution** Run the setup script directly for CI pipelines or automated environments: ```bash ./scripts/setup-codex.sh ``` Both methods populate the `CODEX_HOME` environment variable (defaulting to `~/.codex`) and register the [`codex-companion.sh`](https://github.com/Chachamaru127/claude-code-harness/blob/main/codex-companion.sh) helper that the harness invokes during task execution. ## Delegate Tasks to Codex CLI With the CLI installed and harness configured, append the `--codex` flag to any harness command to force delegation to the Codex engine instead of Claude Code. **Example commands:** ```bash # Run a single work plan via Codex /harness-work --codex ./src/my-feature # Execute the full implementation pipeline /breezing --codex all ``` The `--codex` flag is defined in [`skills/harness-work/SKILL.md`](https://github.com/Chachamaru127/claude-code-harness/blob/main/skills/harness-work/SKILL.md) and the Codex-native variant at [`skills-codex/harness-work/SKILL.md`](https://github.com/Chachamaru127/claude-code-harness/blob/main/skills-codex/harness-work/SKILL.md). When present, the harness performs this sequence: 1. **Serializes** the task description into a JSON payload ([`task.json`](https://github.com/Chachamaru127/claude-code-harness/blob/main/task.json)). 2. **Invokes** the wrapper script [`scripts/codex/codex-exec-wrapper.sh`](https://github.com/Chachamaru127/claude-code-harness/blob/main/scripts/codex/codex-exec-wrapper.sh), which executes: ```bash codex exec --input task.json --output result.json --output-schema ``` 3. **Injects** environment variables (e.g., `CODEX_HOME`) and enforces **quality gates** including AGENTS summary checks and post-execution validation. 4. **Parses** [`result.json`](https://github.com/Chachamaru127/claude-code-harness/blob/main/result.json) back into the harness's internal format for downstream steps like plan review or test execution. For custom automation outside the harness UI, call the wrapper directly: ```bash echo '{"command":"implement","path":"src/featureA"}' > task.json scripts/codex/codex-exec-wrapper.sh task.json result.json ``` ## Verify the Integration The repository includes dedicated tests to validate the Codex pathway. Run these to ensure your configuration is correct: - **[`tests/test-codex-plugin-adapter.sh`](https://github.com/Chachamaru127/claude-code-harness/blob/main/tests/test-codex-plugin-adapter.sh)** – Validates that the manifest advertises "Codex CLI compatibility route" and confirms wrapper output is not derived from Claude Code help output. - **[`tests/test-tool-capability-matrix.sh`](https://github.com/Chachamaru127/claude-code-harness/blob/main/tests/test-tool-capability-matrix.sh)** – Confirms the capability matrix entry "Codex CLI | `internal-compatible`" is present and accurate. Execute the full validation suite via [`./tests/validate-plugin.sh`](https://github.com/Chachamaru127/claude-code-harness/blob/main/./tests/validate-plugin.sh), which automatically exercises the Codex integration in CI environments using the [`check-codex.sh`](https://github.com/Chachamaru127/claude-code-harness/blob/main/check-codex.sh) script. ## Summary - **Install** the Codex CLI using [`./scripts/setup-codex.sh`](https://github.com/Chachamaru127/claude-code-harness/blob/main/./scripts/setup-codex.sh) or `/harness-setup codex`, which handles Node.js checks, npm installation, and PATH configuration. - **Enable** the integration by ensuring `CODEX_HOME` is set and the companion scripts are registered in your environment. - **Delegate** by appending `--codex` to harness commands like `/harness-work` or `/breezing`, which triggers [`scripts/codex/codex-exec-wrapper.sh`](https://github.com/Chachamaru127/claude-code-harness/blob/main/scripts/codex/codex-exec-wrapper.sh) to call `codex exec`. - **Verify** your setup using [`tests/test-codex-plugin-adapter.sh`](https://github.com/Chachamaru127/claude-code-harness/blob/main/tests/test-codex-plugin-adapter.sh) and [`tests/test-tool-capability-matrix.sh`](https://github.com/Chachamaru127/claude-code-harness/blob/main/tests/test-tool-capability-matrix.sh) to confirm compatibility and execution pathways. ## Frequently Asked Questions ### What is the minimum required version of the Codex CLI? The harness requires Codex CLI version **0.134.0** or higher. The [`scripts/setup-codex.sh`](https://github.com/Chachamaru127/claude-code-harness/blob/main/scripts/setup-codex.sh) script explicitly pins this version during `npm install` and validates it by running `codex --version` before completing setup. ### Can I use both Claude Code and Codex CLI with the same harness installation? Yes. The harness treats Codex CLI as an opt-in alternative rather than a replacement. Omit the `--codex` flag to use the native Claude Code engine, or include it to delegate specific tasks to Codex. This flexibility allows you to benchmark outputs or migrate workflows incrementally without reinstalling the harness. ### How does the codex-exec-wrapper.sh handle authentication? The wrapper script inherits your shell environment, including any `CODEX_HOME` settings or API keys configured in your `~/.codex` directory. It does not manage authentication directly; instead, it assumes the `codex` binary has access to necessary credentials through standard OpenAI CLI configuration files or environment variables present at execution time. ### Where does the harness store Codex-specific configuration? Configuration resides in `${CODEX_HOME:-~/.codex}`, typically under `skills/harness-plan` and related subdirectories. Unlike Claude Code's [`AGENTS.md`](https://github.com/Chachamaru127/claude-code-harness/blob/main/AGENTS.md) files, these Codex-specific configs remain in your local workspace only and are not version-controlled within the claude-code-harness repository, preventing conflicts across different user environments.