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

bash

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

2. Run setup

bash

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

bash

npm install -g @openai/codex

4. Authenticate Codex

If Codex is installed but not logged in:

bash

!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:

bash

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

bash

# 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:

bash

# 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:

bash

# 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:

text

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:

bash

# 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:

bash

# Show latest result
/codex:result

# Show specific result
/codex:result task-abc123

Resume in Codex CLI:

bash

codex resume <session-id>

/codex:cancel

Cancels an active background Codex job.

Examples:

bash

# 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:

bash

# 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:

toml

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

Custom OpenAI base URL:

In your Codex config:

toml

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:

bash

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

See Codex config reference for full options.

Workflow Patterns

Review Before Shipping

bash

/codex:review

Wait for output, address feedback, commit.

Adversarial Pre-Ship Review

bash

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

Use this to pressure-test critical design decisions.

Delegate Bug Investigation

bash

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

Check in later:

bash

/codex:status
/codex:result

Quick Fix with Spark Model

bash

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

Resume Previous Rescue

bash

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

Long-Running Background Task

bash

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

Monitor:

bash

/codex:status

Retrieve:

bash

/codex:result

Cancel if needed:

bash

/codex:cancel

Continue Work in Codex CLI

After

/codex:result

, copy the session ID and resume directly in Codex:

bash

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:

javascript

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

javascript

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

javascript

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:

bash

npm install -g @openai/codex

Then re-run:

bash

/codex:setup

Authentication Failed

Symptom: Codex commands fail with authentication error.

Solution:

bash

!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:

bash

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

bash

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

bash

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:

bash

# 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):

toml

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

.codex/config-high.toml
:

toml

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

Switch in shell before running commands:

bash

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:

bash

/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

.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-plugin-claude-code

NPX Install

Tags

SKILL.md Content

Codex Plugin for Claude Code

Overview

Requirements

Installation

1. Add the marketplace and install the plugin

2. Run setup

3. Install Codex CLI (if needed)

4. Authenticate Codex

5. Verify

Commands

/codex:review

/codex:adversarial-review

/codex:rescue

/codex:status

/codex:result

/codex:cancel

/codex:setup

Configuration

Common Configurations

Workflow Patterns

Review Before Shipping

Adversarial Pre-Ship Review

Delegate Bug Investigation

Quick Fix with Spark Model

Resume Previous Rescue

Long-Running Background Task

Continue Work in Codex CLI

Code Examples

JavaScript: Triggering Codex Review from a Script

JavaScript: Checking Codex Job Status

JavaScript: Delegating Task with Environment Config

Troubleshooting

Codex Not Found

Authentication Failed

Background Job Stuck

Review Gate Draining Usage

Custom Base URL Not Picked Up

Node.js Version Too Old

Advanced Usage

Combining with Claude Code Native Commands

Using Codex Config Profiles

Resuming Codex Sessions

Summary

`/codex:review`

`/codex:adversarial-review`

`/codex:rescue`

`/codex:status`

`/codex:result`

`/codex:cancel`

`/codex:setup`