Codex Plugin Claude Code

Codex Plugin for Claude Code

Skill by ara.so — Codex Skills collection.

Overview

The codex-plugin-cc enables Claude Code users to leverage OpenAI Codex directly from their workflow. You can request code reviews (standard or adversarial), delegate tasks to Codex as a background subagent, and manage long-running Codex jobs—all without leaving Claude Code.

Key capabilities:

• /codex:review — standard read-only Codex code review
• /codex:adversarial-review — steerable review that challenges design decisions
• /codex:rescue — delegate investigation/fix tasks to Codex subagent
• /codex:status, /codex:result, /codex:cancel — manage background jobs

Requirements

• Node.js 18.18+
• ChatGPT subscription (including Free tier) or OpenAI API key
• Codex CLI (the plugin can help install it via /codex:setup)

Usage contributes to your Codex usage limits.

Installation

1. Add the marketplace and install the plugin

/plugin marketplace add openai/codex-plugin-cc
/plugin install codex@openai-codex
/reload-plugins

2. Run setup

/codex:setup

This checks if Codex is installed and authenticated. If missing and npm is available, it can offer to install Codex for you.

3. Install Codex CLI (if needed)

If you prefer manual installation:

npm install -g @openai/codex

4. Authenticate Codex

If Codex is installed but not logged in:

!codex login

Follow the prompts to sign in with ChatGPT or API key.

5. Verify

After setup, you should see:

• Slash commands: /codex:review, /codex:adversarial-review, /codex:rescue, /codex:status, /codex:result, /codex:cancel, /codex:setup
• Subagent: codex:codex-rescue in /agents

Test it:

/codex:review --background
/codex:status
/codex:result

Commands

/codex:review

Runs a standard Codex code review on uncommitted changes or branch diff.

Flags:

• --base <ref> — compare against a base branch (e.g., main)
• --wait — wait synchronously for result
• --background — run asynchronously (recommended for multi-file changes)

Examples:

# Review uncommitted changes
/codex:review

# Review current branch vs main
/codex:review --base main

# Run in background
/codex:review --background

Notes:

• Read-only, no modifications
• Use /codex:status and /codex:result for background jobs

/codex:adversarial-review

Runs a steerable review that challenges implementation and design choices. Useful for pressure-testing assumptions, tradeoffs, and alternative approaches.

Flags:

• Same as /codex:review: --base, --wait, --background
• Accepts focus text after flags to steer the review

Examples:

# General adversarial review
/codex:adversarial-review

# Challenge caching and retry design
/codex:adversarial-review --base main challenge whether this was the right caching and retry design

# Focus on race conditions
/codex:adversarial-review --background look for race conditions and question the chosen approach

Use cases:

• Pre-ship review challenging direction, not just code details
• Testing design choices, hidden assumptions, alternative approaches
• Pressure-testing auth, data loss, rollback, race conditions, reliability

/codex:rescue

Delegates a task to Codex through the codex:codex-rescue subagent. Codex will investigate, fix, or continue work.

Flags:

• --background — run asynchronously (recommended for long tasks)
• --wait — wait synchronously
• --resume — continue latest rescue thread for this repo
• --fresh — start a new rescue thread
• --model <model> — specify model (e.g., gpt-5.4-mini, spark)
• --effort <level> — reasoning effort: low, medium, high

Examples:

# Investigate test failure
/codex:rescue investigate why the tests started failing

# Fix with smallest safe patch
/codex:rescue fix the failing test with the smallest safe patch

# Resume latest rescue
/codex:rescue --resume apply the top fix from the last run

# Use specific model and effort
/codex:rescue --model gpt-5.4-mini --effort medium investigate the flaky integration test

# Quick fix with spark
/codex:rescue --model spark fix the issue quickly

# Background investigation
/codex:rescue --background investigate the regression

Natural delegation:

You can also ask naturally:

Ask Codex to redesign the database connection to be more resilient.

Notes:

• If --model or --effort omitted, Codex uses its own defaults
• spark maps to gpt-5.3-codex-spark
• Follow-up rescues can continue the latest task

/codex:status

Shows running and recent Codex jobs for the current repository.

Examples:

# Show all jobs
/codex:status

# Show specific job
/codex:status task-abc123

Use cases:

• Check background work progress
• See latest completed job
• Confirm if task still running

/codex:result

Shows final output for a finished job. Includes Codex session ID for resuming in Codex CLI.

Examples:

# Show latest result
/codex:result

# Show specific result
/codex:result task-abc123

Resume in Codex CLI:

codex resume <session-id>

/codex:cancel

Cancels an active background Codex job.

Examples:

# Cancel latest job
/codex:cancel

# Cancel specific job
/codex:cancel task-abc123

/codex:setup

Checks if Codex is installed and authenticated. Can install Codex if npm is available. Also manages optional review gate.

Examples:

# Check setup
/codex:setup

# Enable review gate (advanced)
/codex:setup --enable-review-gate

# Disable review gate
/codex:setup --disable-review-gate

Review gate:

• Uses a Stop hook to run targeted Codex review based on Claude's response
• Blocks stop if issues found, so Claude can address them
• Warning: Can create long Claude/Codex loops and drain usage limits quickly

Configuration

The plugin uses your local Codex CLI configuration. Config is picked up from:

• User-level: ~/.codex/config.toml
• Project-level: .codex/config.toml (must be trusted)

Common Configurations

Set default model and reasoning effort:

Create .codex/config.toml at the root of your project:

model = "gpt-5.4-mini"
model_reasoning_effort = "high"

Custom OpenAI base URL:

In your Codex config:

openai_base_url = "https://your-custom-endpoint.example.com"

Use environment variables for API keys:

Codex respects OPENAI_API_KEY if you're using API key authentication:

export OPENAI_API_KEY=your-api-key-here
codex login

See Codex config reference for full options.

Workflow Patterns

Review Before Shipping

/codex:review

Wait for output, address feedback, commit.

Adversarial Pre-Ship Review

/codex:adversarial-review --base main challenge the retry and timeout strategy

Use this to pressure-test critical design decisions.

Delegate Bug Investigation

/codex:rescue --background investigate why the build is failing in CI

Check in later:

/codex:status
/codex:result

Quick Fix with Spark Model

/codex:rescue --model spark fix the linter error quickly

Resume Previous Rescue

/codex:rescue --resume apply the suggested fix from the last run

Long-Running Background Task

/codex:adversarial-review --background
/codex:rescue --background investigate the flaky test

Monitor:

/codex:status

Retrieve:

/codex:result

Cancel if needed:

/codex:cancel

Continue Work in Codex CLI

After /codex:result, copy the session ID and resume directly in Codex:

codex resume abc123-session-id

This lets you review Codex's work or continue it there.

Code Examples

JavaScript: Triggering Codex Review from a Script

While the plugin is used via Claude Code slash commands, you can programmatically trigger Codex CLI tasks in Node.js:

const { execSync } = require('child_process');

function runCodexReview(baseBranch = null) {
  let cmd = 'codex review';
  if (baseBranch) {
    cmd += ` --base ${baseBranch}`;
  }
  try {
    const output = execSync(cmd, { encoding: 'utf-8' });
    console.log(output);
  } catch (error) {
    console.error('Codex review failed:', error.message);
  }
}

runCodexReview('main');

JavaScript: Checking Codex Job Status

const { execSync } = require('child_process');

function getCodexStatus(taskId = null) {
  let cmd = 'codex status';
  if (taskId) {
    cmd += ` ${taskId}`;
  }
  try {
    const output = execSync(cmd, { encoding: 'utf-8' });
    return JSON.parse(output); // Adjust based on actual Codex CLI output format
  } catch (error) {
    console.error('Failed to get Codex status:', error.message);
    return null;
  }
}

const status = getCodexStatus();
console.log(status);

JavaScript: Delegating Task with Environment Config

const { execSync } = require('child_process');

function delegateToCodex(task, model = 'gpt-5.4-mini', effort = 'medium') {
  // Ensure Codex uses the right config
  process.env.CODEX_MODEL = model;
  process.env.CODEX_REASONING_EFFORT = effort;

  const cmd = `codex rescue "${task}"`;
  try {
    const output = execSync(cmd, { encoding: 'utf-8' });
    console.log('Codex rescue output:', output);
  } catch (error) {
    console.error('Codex rescue failed:', error.message);
  }
}

delegateToCodex('investigate the failing integration test');

Troubleshooting

Codex Not Found

Symptom: /codex:setup reports Codex is not installed.

Solution:

npm install -g @openai/codex

Then re-run:

/codex:setup

Authentication Failed

Symptom: Codex commands fail with authentication error.

Solution:

!codex login

Follow the prompts to sign in with ChatGPT or API key.

Background Job Stuck

Symptom: /codex:status shows job running for too long.

Solution:

/codex:cancel

Then retry or investigate Codex logs.

Review Gate Draining Usage

Symptom: Review gate creates long Claude/Codex loops.

Solution:

Disable the review gate:

/codex:setup --disable-review-gate

Only enable when actively monitoring.

Custom Base URL Not Picked Up

Symptom: Codex ignores openai_base_url config.

Solution:

Ensure .codex/config.toml is in the project root and the project is trusted. See Codex config docs.

Node.js Version Too Old

Symptom: Plugin fails to load or Codex CLI errors.

Solution:

Upgrade to Node.js 18.18+:

nvm install 18
nvm use 18

Or use your system's package manager.

Advanced Usage

Combining with Claude Code Native Commands

You can alternate between Claude Code's native review and Codex's review:

# Claude review
/review

# Codex adversarial review
/codex:adversarial-review --base main challenge the error handling strategy

Using Codex Config Profiles

Define multiple configs and switch via environment:

.codex/config.toml (default):

model = "gpt-5.4-mini"
model_reasoning_effort = "medium"

.codex/config-high.toml:

model = "gpt-5.4"
model_reasoning_effort = "high"

Switch in shell before running commands:

export CODEX_CONFIG=.codex/config-high.toml
/codex:rescue investigate the race condition thoroughly

(Exact mechanism depends on Codex CLI support; adjust as needed.)

Resuming Codex Sessions

After a rescue or review, grab the session ID from /codex:result and resume in Codex CLI for deeper investigation:

/codex:result
# Copy session ID: abc123-xyz

# In terminal
codex resume abc123-xyz

Summary

The Codex plugin for Claude Code bridges two powerful AI coding tools:

• Standard reviews: /codex:review
• Adversarial reviews: /codex:adversarial-review
• Task delegation: /codex:rescue
• Job management: /codex:status, /codex:result, /codex:cancel

Install, authenticate, and leverage Codex's deep code understanding alongside Claude Code's agent workflow. Use background jobs for long tasks, adversarial reviews for design challenges, and rescue for delegating investigations and fixes.

Configuration: Uses your local Codex CLI config (~/.codex/config.toml or .codex/config.toml).

Authentication: Same as Codex CLI (codex login).

Workflow: Delegate to Codex, check status, retrieve results, or resume in Codex CLI for deeper work.

Resources:

• Codex CLI Reference
• Codex Config Reference
• Codex Pricing
• Plugin Repository