How to Configure claude-code-harness to Integrate with Codex CLI Instead of Claude Code

To configure claude-code-harness for Codex CLI integration, install the Codex CLI using ./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:

./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 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:

/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.

Method 2: Manual execution

Run the setup script directly for CI pipelines or automated environments:

./scripts/setup-codex.sh

Both methods populate the CODEX_HOME environment variable (defaulting to ~/.codex) and register the 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:

# 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 and the Codex-native variant at skills-codex/harness-work/SKILL.md. When present, the harness performs this sequence:

1. Serializes the task description into a JSON payload (task.json).

2. Invokes the wrapper script scripts/codex/codex-exec-wrapper.sh, which executes:

   codex exec --input task.json --output result.json --output-schema <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 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:

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 – 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 – Confirms the capability matrix entry "Codex CLI | internal-compatible" is present and accurate.

Execute the full validation suite via ./tests/validate-plugin.sh, which automatically exercises the Codex integration in CI environments using the check-codex.sh script.

Summary

• Install the Codex CLI using ./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 to call codex exec.
• Verify your setup using tests/test-codex-plugin-adapter.sh and 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}