Codex plugin for Claude Code

Use Codex from inside Claude Code for code reviews or to delegate tasks to Codex.

This plugin is for Claude Code users who want an easy way to start using Codex from the workflow they already have.

What You Get

• /codex:review for a normal read-only Codex review
• /codex:adversarial-review for a steerable challenge review
• /codex:deep-review for a multi-dimensional review of correctness, conciseness, and code quality
• /codex:implement to have Codex implement a structured plan with per-task implementer and reviewer agents
• /codex:rescue, /codex:transfer, /codex:status, /codex:result, and /codex:cancel to delegate work, hand off sessions, and manage background jobs

Requirements

• ChatGPT subscription (incl. Free) or OpenAI API key.
  • Usage will contribute to your Codex usage limits. Learn more.
• Node.js 18.18 or later

Install

Add the marketplace in Claude Code:

/plugin marketplace add patriyang/codex-plugin-cc

That repo declares the marketplace as patricks-plugins, which is the name every later /plugin command uses.

Install the plugin:

/plugin install codex@patricks-plugins

Reload plugins:

/reload-plugins

For existing installs, /reload-plugins only reloads local files. To pick up a newly published plugin version, run /plugin marketplace update patricks-plugins, then update or reinstall the codex plugin.

Then run:

/codex:setup

/codex:setup will tell you whether Codex is ready. If Codex is missing and npm is available, it can offer to install Codex for you.

If you prefer to install Codex yourself, use:

npm install -g @openai/codex

If Codex is installed but not logged in yet, run:

!codex login

After install, you should see:

• the slash commands listed below
• the codex:codex-rescue subagent in /agents

One simple first run is:

/codex:review --background

Usage

/codex:review

Runs a normal Codex review on your current work. It gives you the same quality of code review as running /review inside Codex directly.

Note

Code review especially for multi-file changes might take a while. It's generally recommended to run it in the background.

Use it when you want:

• a review of your current uncommitted changes
• a review of your branch compared to a base branch like main

Use --base <ref> for branch review. It also supports --wait and --background. It is not steerable and does not take custom focus text. Use /codex:adversarial-review when you want to challenge a specific decision or risk area.

Examples:

/codex:review
/codex:review --base main
/codex:review --background

This command is read-only and will not perform any changes. A background review runs as a detached tracked job with a job ID; Claude waits on that job and presents the findings as soon as it finishes, so you should not have to prompt it to continue. Use /codex:cancel to cancel an ongoing run.

/codex:adversarial-review

Runs a steerable review that questions the chosen implementation and design.

It can be used to pressure-test assumptions, tradeoffs, failure modes, and whether a different approach would have been safer or simpler.

It uses the same review target selection as /codex:review, including --base <ref> for branch review. It also supports --wait and --background. Unlike /codex:review, it can take extra focus text after the flags.

Use it when you want:

• a review before shipping that challenges the direction, not just the code details
• review focused on design choices, tradeoffs, hidden assumptions, and alternative approaches
• pressure-testing around specific risk areas like auth, data loss, rollback, race conditions, or reliability

Examples:

/codex:adversarial-review
/codex:adversarial-review --base main challenge whether this was the right caching and retry design
/codex:adversarial-review --background look for race conditions and question the chosen approach

This command is read-only. It does not fix code.

/codex:deep-review

Runs a multi-dimensional review that evaluates the change across three lenses in a single pass:

• correctness — logic errors, edge cases, regressions, and data-safety issues
• conciseness — reuse, simplification, and efficiency, the same intent as a /simplify pass
• code quality — naming, readability, structure, and consistency with the surrounding code

Each finding is tagged with its dimension ([correctness], [conciseness], or [quality]).

It uses the same review target selection as /codex:review, including --base <ref> for branch review. It also supports --wait and --background. Like /codex:adversarial-review, it can take extra focus text after the flags.

By default /codex:deep-review uses gpt-5.6-sol with high reasoning effort. Override either per run with --model <model|spark> and --effort <none|minimal|low|medium|high|xhigh|max|ultra> (also accepted by /codex:adversarial-review). The native /codex:review path does not support --effort. Every review reports the model it ran under in its output, so the resolved config is checkable after the fact; /codex:deep-review and /codex:adversarial-review also report an Effort: line — the resolved effort, or codex default when none is pinned — while /codex:review reports no effort, because it sends none.

Use it when you want:

• one thorough pass that covers defects, cleanup opportunities, and maintainability together
• a pre-merge review that goes beyond correctness to flag code that could be simpler or clearer

Examples:

/codex:deep-review
/codex:deep-review --base main
/codex:deep-review --background focus on the new caching layer

This command is read-only. It does not fix code.

/codex:rescue

Hands a task to Codex through the codex:codex-rescue subagent.

Use it when you want Codex to:

• investigate a bug
• try a fix
• continue a previous Codex task
• take a faster or cheaper pass with a smaller model

Note

Depending on the task and the model you choose these tasks might take a long time. With --background, rescue enqueues a tracked Codex job, waits for it in bounded foreground steps, and presents the persisted result like the review commands do.

It supports --background, --wait, --resume, and --fresh. If you omit --resume and --fresh, the plugin can offer to continue the latest rescue thread for this repo.

Examples:

/codex:rescue investigate why the tests started failing
/codex:rescue fix the failing test with the smallest safe patch
/codex:rescue --resume apply the top fix from the last run
/codex:rescue --model gpt-5.4-mini --effort medium investigate the flaky integration test
/codex:rescue --model spark fix the issue quickly
/codex:rescue --background investigate the regression

You can also just ask for a task to be delegated to Codex:

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

Notes:

• if you do not pass --model or --effort, /codex:rescue uses gpt-5.5 with high reasoning effort. Other commands pin their own defaults — see Common Configurations.
• if you say spark, the plugin maps that to gpt-5.3-codex-spark
• follow-up rescue requests can continue the latest Codex task in the repo
• for task and the review commands, flags must precede the prompt/focus text (anything after it is literal, not a flag); /codex:status, /codex:result, and /codex:cancel instead take their job id first and flags after.
• a prompt whose first word is a flag name must be passed after a bare -- (for example, task -- --write access is missing), otherwise it is consumed as a real flag.

/codex:implement

Implements a structured plan through Codex subagent-driven development.

By default, Claude acts as the controller and runs each task in sequence:

1. a fresh Codex implementer makes the change; Claude (the controller) commits it
2. a fresh Codex spec reviewer checks the result against the task
3. a fresh Codex code quality reviewer checks the implementation
4. Codex loops on reviewer feedback until the task is approved or blocked

At the end, the command reports what was completed, bugs flagged, deviations from the plan, and suggested next steps.

Use it when you have:

• a written implementation plan with numbered tasks or a checklist
• a plan file you want Codex to execute task by task
• a longer coding effort where independent Codex reviewer passes are useful

The plan can come from inline text, a file path, or the most recent plan-like content in the current Claude conversation. If no explicit plan is passed, the command asks you to confirm the plan it found before starting.

It supports --sequential, --single-shot, --background, --wait, --model <model|spark>, and --effort <none|minimal|low|medium|high|xhigh|max|ultra>. If omitted, /codex:implement uses gpt-5.6-luna with xhigh reasoning effort; capacity blocks step effort up when the model supports the next level, otherwise they escalate to a stronger model.

Examples:

/codex:implement plans/auth-refresh.md
/codex:implement --model gpt-5.4-mini --effort high plans/auth-refresh.md
/codex:implement --single-shot implement the plan above

Note

The default sequential mode is write-capable. Codex edits files; Claude commits each completed task through scoped controller Git metadata escalation (Codex's sandbox cannot write the git index, especially in worktrees). It works best from a feature branch with a clean working tree.

/codex:transfer

Creates a persistent Codex thread from the current Claude Code session and prints a codex resume <session-id> command.

Use it when you started a debugging or implementation conversation in Claude Code and want to continue that same context directly in Codex.

Examples:

/codex:transfer
/codex:transfer --source ~/.claude/projects/-Users-me-repo/<session-id>.jsonl

The plugin's existing SessionStart hook supplies the current transcript path automatically; --source is available as a manual override. The transfer uses Codex's external-agent session importer, so it follows the same conversion rules as importing Claude history in the Codex App and creates visible turns that can be continued in the App or TUI. The source must be under ~/.claude/projects, and older Codex versions that do not expose session import must be upgraded before using this command.

/codex:status

Shows running and recent Codex jobs for the current repository.

Examples:

/codex:status
/codex:status task-abc123
/codex:status task-abc123 --wait
/codex:status task-abc123 --wait --timeout-ms 600000

Use it to:

• check progress on background work
• see the latest completed job
• confirm whether a task is still running
• block until a specific job finishes (--wait, which requires a job ID)

--wait polls that one job until it reaches a terminal state, reaping the record if the underlying process died. Without a job ID it errors rather than waiting on the whole table.

/codex:result

Shows the final stored Codex output for a finished job. When available, it also includes the Codex session ID so you can reopen that run directly in Codex with codex resume <session-id>.

Examples:

/codex:result
/codex:result task-abc123

/codex:cancel

Cancels an active background Codex job.

Examples:

/codex:cancel
/codex:cancel task-abc123

/codex:setup

Checks whether Codex is installed and authenticated. If Codex is missing and npm is available, it can offer to install Codex for you.

You can also use /codex:setup to manage the optional review gate and the backup model.

Choosing a backup model

/codex:setup --fallback-model gpt-5.6-terra
/codex:setup --clear-fallback-model

When a Codex run is rejected because the selected model is at capacity, the plugin retries the run once on a backup model instead of failing. Capacity rejections are transient and have nothing to do with your prompt, so the same work usually succeeds immediately on another model.

The backup model is resolved in this order:

1. the CODEX_COMPANION_FALLBACK_MODEL environment variable — set it to none to turn the fallback off entirely
2. the model configured with /codex:setup --fallback-model
3. whatever Codex itself advertises, picking its default model and skipping the one that was at capacity

Nothing is hardcoded, so the third step keeps working as OpenAI renames models.

The retry only happens when the rejected turn produced nothing at all — no output, no commands, no file edits. A capacity rejection that arrives after work has started leaves the run failed rather than risking a repeat of something that already ran.

Either way the failure is machine-readable: /codex:status and /codex:result report failureClass and retryable in their JSON, so a caller never has to pattern-match an error message to tell a transient capacity rejection from a real failure.

retryable: true means the turn produced nothing, so repeating it is safe — not that repeating it immediately will help. A retryable failure that only time can clear also carries retryAfterMs, and a caller should wait at least that long before re-dispatching. Capacity rejections carry a 60-second floor: backup-model resolution is deterministic, so an immediate retry picks the same models and can fail identically, which is exactly how a fan-out of automated callers spins through a capacity window without making progress. A retryAfterMs is only ever present alongside retryable: true; failureClass: "state-drift" is retryable with no pacing, because re-running it is not waiting on anything.

Failure classes

failureClass	Meaning	retryable
capacity	The model was at capacity and the backup was too, or there was no backup to fall back to.	true when the turn produced nothing, with a retryAfterMs floor of 60s
stalled	The turn's watchdog interrupted it: a tool call or the model itself went silent past its budget. The run produced no verdict — this is what distinguishes an aborted review from one that completed and found nothing.	true only when the turn produced nothing at all; no pacing, since waiting is not what fixes it
state-drift	A background review's repository moved between enqueue and execution.	true, no pacing
null	Anything else. Read failureMessage.	false

Enabling review gate

/codex:setup --enable-review-gate
/codex:setup --disable-review-gate

When the review gate is enabled, the plugin uses a Stop hook to run a targeted Codex review based on Claude's response. If that review finds issues, the stop is blocked so Claude can address them first.

Warning

The review gate can create a long-running Claude/Codex loop and may drain usage limits quickly. Only enable it when you plan to actively monitor the session.

Typical Flows

Review Before Shipping

/codex:review

Hand A Problem To Codex

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

Implement A Plan

/codex:implement plans/checkout-refactor.md

Start Something Long-Running

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

Neither flow requires user polling because the command waits in bounded foreground steps and presents the result itself.

For a review, --background enqueues a detached tracked job and the command then waits on it in bounded foreground steps, so it presents the findings itself without needing anything from you.

For rescue, --background enqueues a tracked Codex job and the command waits for it in bounded foreground steps, then presents the persisted result just like a background review. If a turn ends before the result is read, recover it with the commands below instead of re-running it.

/codex:status and /codex:result <job-id> inspect a tracked job from another turn, or recover a run whose turn ended before its result was read.

A background review pins the target it resolved at enqueue time, along with the repository state that target points at. If the repository moves before the detached worker starts — you commit the changes it was going to review, switch branches, or the base branch is deleted — the job fails with failureClass: "state-drift" and retryable: true rather than reviewing whatever is there now. Re-running the review picks up the new state. This trades a rare visible failure for the far worse alternative: a clean review of a change nobody looked at.

Codex Integration

The Codex plugin wraps the Codex app server. It uses the global codex binary installed in your environment and applies the same configuration.

Common Configurations

Defaults are per command, not global. Use --model or --effort on a plugin command to override them for one run.

Command	Default model	Default effort
/codex:rescue (and delegated tasks)	gpt-5.5	high
/codex:review	gpt-5.5	(none sent — --effort is rejected)
/codex:adversarial-review	gpt-5.5	(none sent — Codex's own default)
/codex:deep-review	gpt-5.6-sol	high
/codex:implement	gpt-5.6-luna	xhigh

gpt-5.5 / high is the runtime default that applies when a command pins nothing of its own. /codex:deep-review and /codex:implement pin their own model and effort, so they do not run on gpt-5.5. Passing spark to --model maps to gpt-5.3-codex-spark.

Note: the plugin sends a model on every Codex thread it starts, so the model key in your .codex/config.toml never selects the model for a plugin command — the table above does. The model_reasoning_effort key still applies, but only to the commands that send no effort of their own (/codex:review, and /codex:adversarial-review when you do not pass --effort). An explicit --model / --effort overrides both. To change the runtime default without flags, you'd need to edit the plugin's DEFAULT_CODEX_MODEL / DEFAULT_CODEX_REASONING_EFFORT; the per-command defaults above are pinned separately at each command's own call site.

Your configuration will be picked up based on:

• user-level config in ~/.codex/config.toml
• project-level overrides in .codex/config.toml
• project-level overrides only load when the project is trusted

Check out the Codex docs for more configuration options.

Stall Budgets

A turn that goes silent is interrupted rather than left to hang. Four budgets decide when that happens, each overridable by environment variable:

Variable	Default	What it bounds
CODEX_TURN_STALL_TIMEOUT_MS	15m	Silence on the turn as a whole. It is also the outer bound: a tool budget larger than this is clamped to it.
CODEX_TOOL_STALL_TIMEOUT_MS	90s	Silence while a quick tool (web search, custom tool) is in flight.
CODEX_MCP_TOOL_STALL_TIMEOUT_MS	180s	Silence while an MCP tool call is in flight. MCP calls get their own, more patient budget because they can legitimately run longer than a local tool, and interrupting one costs the entire turn — every finding and every file read accumulated so far — not just the call.
CODEX_TOOL_MAX_INFLIGHT_MS	5m	Wall-clock cap on a single quick tool, whether or not it is streaming. Catches a tool that stays chatty but never finishes.

While several quick tools are in flight, the most patient one sets the window, since the watchdog is asking whether anything at all is happening on the turn. When one fires, the run fails with failureClass: "stalled".

MCP Servers

Threads this plugin starts inherit whatever MCP servers your ~/.codex/config.toml configures; the plugin does not add or configure any of its own.

Those threads are non-interactive by construction — they run with approvalPolicy: "never" and there is nobody at the keyboard to answer a prompt — so the plugin approves MCP tool calls on its own. That is a real consequence worth knowing: an MCP server you have configured can be called, unattended, by any reviewer or delegated task this plugin runs, and an MCP tool is not confined by the thread's sandbox the way a shell command is.

To keep a particular server out of these threads, name it in CODEX_DISABLED_MCP_SERVERS:

Variable	Default	What it does
CODEX_DISABLED_MCP_SERVERS	(unset)	Comma-separated MCP server names to disable on threads this plugin starts. Your interactive codex sessions are unaffected.

export CODEX_DISABLED_MCP_SERVERS=codegraph,some-other-server

Names must match [A-Za-z0-9_-]+ — the plugin splices each one into a Codex config path, and a name needing quotes would make Codex read it as a new server definition and fail the thread outright. Anything else is skipped with a warning on stderr, leaving that server enabled.

Moving The Work Over To Codex

Delegated tasks and any stop gate run can also be directly resumed inside Codex by running codex resume either with the specific session ID you received from running /codex:result or /codex:status or by selecting it from the list.

This way you can review the Codex work or continue the work there.

FAQ

Do I need a separate Codex account for this plugin?

If you are already signed into Codex on this machine, that account should work immediately here too. This plugin uses your local Codex CLI authentication.

If you only use Claude Code today and have not used Codex yet, you will also need to sign in to Codex with either a ChatGPT account or an API key. Codex is available with your ChatGPT subscription, and codex login supports both ChatGPT and API key sign-in. Run /codex:setup to check whether Codex is ready, and use !codex login if it is not.

Does the plugin use a separate Codex runtime?

No. This plugin delegates through your local Codex CLI and Codex app server on the same machine.

That means:

• it uses the same Codex install you would use directly
• it uses the same local authentication state
• it uses the same repository checkout and machine-local environment

Will it use the same Codex config I already have?

Yes. If you already use Codex, the plugin picks up the same configuration.

Can I keep using my current API key or base URL setup?

Yes. Because the plugin uses your local Codex CLI, your existing sign-in method and config still apply.

If you need to point the built-in OpenAI provider at a different endpoint, set openai_base_url in your Codex config.