OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add reason-machines/codex-skills --skill codex-plugin-claude-code
Use OpenAI Codex from inside Claude Code for code reviews, adversarial reviews, and delegating tasks to Codex as a subagent.
npx skills add reason-machines/codex-skills --skill codex-plugin-claude-code
Skill by ara.so — Codex Skills collection.
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/codex:setup)Usage contributes to your Codex usage limits.
This checks if Codex is installed and authenticated. If missing and npm is available, it can offer to install Codex for you.
If you prefer manual installation:
If Codex is installed but not logged in:
Follow the prompts to sign in with ChatGPT or API key.
After setup, you should see:
/codex:review, /codex:adversarial-review, /codex:rescue, /codex:status, /codex:result, /codex:cancel, /codex:setupcodex:codex-rescue in /agentsTest it:
/codex:reviewRuns 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:
Notes:
/codex:status and /codex:result for background jobs/codex:adversarial-reviewRuns a steerable review that challenges implementation and design choices. Useful for pressure-testing assumptions, tradeoffs, and alternative approaches.
Flags:
/codex:review: --base, --wait, --backgroundExamples:
Use cases:
/codex:rescueDelegates 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, highExamples:
Natural delegation:
You can also ask naturally:
Notes:
--model or --effort omitted, Codex uses its own defaultsspark maps to gpt-5.3-codex-spark/codex:statusShows running and recent Codex jobs for the current repository.
Examples:
Use cases:
/codex:resultShows final output for a finished job. Includes Codex session ID for resuming in Codex CLI.
Examples:
Resume in Codex CLI:
/codex:cancelCancels an active background Codex job.
Examples:
/codex:setupChecks if Codex is installed and authenticated. Can install Codex if npm is available. Also manages optional review gate.
Examples:
Review gate:
Stop hook to run targeted Codex review based on Claude's responseThe plugin uses your local Codex CLI configuration. Config is picked up from:
~/.codex/config.toml.codex/config.toml (must be trusted)Set default model and reasoning effort:
Create .codex/config.toml at the root of your project:
Custom OpenAI base URL:
In your Codex config:
Use environment variables for API keys:
Codex respects OPENAI_API_KEY if you're using API key authentication:
See Codex config reference for full options.
Wait for output, address feedback, commit.
Use this to pressure-test critical design decisions.
Check in later:
Monitor:
Retrieve:
Cancel if needed:
After /codex:result, copy the session ID and resume directly in Codex:
This lets you review Codex's work or continue it there.
While the plugin is used via Claude Code slash commands, you can programmatically trigger Codex CLI tasks in Node.js:
Symptom: /codex:setup reports Codex is not installed.
Solution:
Then re-run:
Symptom: Codex commands fail with authentication error.
Solution:
Follow the prompts to sign in with ChatGPT or API key.
Symptom: /codex:status shows job running for too long.
Solution:
Then retry or investigate Codex logs.
Symptom: Review gate creates long Claude/Codex loops.
Solution:
Disable the review gate:
Only enable when actively monitoring.
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.
Symptom: Plugin fails to load or Codex CLI errors.
Solution:
Upgrade to Node.js 18.18+:
Or use your system's package manager.
You can alternate between Claude Code's native review and Codex's review:
Define multiple configs and switch via environment:
.codex/config.toml (default):
.codex/config-high.toml:
Switch in shell before running commands:
(Exact mechanism depends on Codex CLI support; adjust as needed.)
After a rescue or review, grab the session ID from /codex:result and resume in Codex CLI for deeper investigation:
The Codex plugin for Claude Code bridges two powerful AI coding tools:
/codex:review/codex:adversarial-review/codex:rescue/codex:status, /codex:result, /codex:cancelInstall, 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 login!codex login/codex:review --background
/codex:status
/codex:result# Review uncommitted changes
/codex:review
# Review current branch vs main
/codex:review --base main
# Run in background
/codex:review --background# 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# 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 regressionAsk Codex to redesign the database connection to be more resilient.# Show all jobs
/codex:status
# Show specific job
/codex:status task-abc123# Show latest result
/codex:result
# Show specific result
/codex:result task-abc123codex resume <session-id># Cancel latest job
/codex:cancel
# Cancel specific job
/codex:cancel task-abc123# Check setup
/codex:setup
# Enable review gate (advanced)
/codex:setup --enable-review-gate
# Disable review gate
/codex:setup --disable-review-gatemodel = "gpt-5.4-mini"
model_reasoning_effort = "high"openai_base_url = "https://your-custom-endpoint.example.com"export OPENAI_API_KEY=your-api-key-here
codex login/codex:review/codex:adversarial-review --base main challenge the retry and timeout strategy/codex:rescue --background investigate why the build is failing in CI/codex:status
/codex:result/codex:rescue --model spark fix the linter error quickly/codex:rescue --resume apply the suggested fix from the last run/codex:adversarial-review --background
/codex:rescue --background investigate the flaky test/codex:status/codex:result/codex:cancel/codex:cancelcodex resume abc123-session-idconst { 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');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);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');/codex:setup --disable-review-gatenvm install 18
nvm use 18# Claude review
/review
# Codex adversarial review
/codex:adversarial-review --base main challenge the error handling strategymodel = "gpt-5.4-mini"
model_reasoning_effort = "medium"model = "gpt-5.4"
model_reasoning_effort = "high"export CODEX_CONFIG=.codex/config-high.toml
/codex:rescue investigate the race condition thoroughly/codex:result
# Copy session ID: abc123-xyz
# In terminal
codex resume abc123-xyz