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.

This is a fork of openai/codex-plugin-cc, maintained by vibecodedapps-official. See Differences from upstream for what changed and why.

What You Get

• /codex:review for a normal read-only Codex review
• /codex:adversarial-review for a steerable challenge review
• /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

Important

This fork keeps the plugin name codex, so its commands are still /codex:*. If the upstream plugin is already installed, uninstall it first with /plugin uninstall codex@openai-codex. Two plugins with the same name clash, and you cannot tell from a /codex:* command which one ran.

Add the marketplace in Claude Code:

/plugin marketplace add vibecodedapps-official/codex-plugin-cc

Install the plugin:

/plugin install codex@vibecodedapps-codex

Reload plugins:

/reload-plugins

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.

It also checks one permission rule. /codex:rescue writes your request to a file outside your project, which Claude Code asks you to approve unless a rule allows it, so setup prints the exact rule for your machine when it is missing. See the rescue section for what the rule does and why the request travels in a file.

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
• the version in /plugin matching the version in .claude-plugin/marketplace.json

Note

The installer skips a rebuild when the plugin version string has not changed. A fix merged without a version bump therefore does not reach a copy you already installed. Every release here bumps the version, so reinstall after a release rather than after a merge; if you track main directly, uninstall and reinstall to pick a merge up.

One simple first run is:

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

Differences From Upstream

Everything upstream does, this fork still does. What follows is what it does differently. The commit history is the full record; this is the summary a visitor needs before choosing between the two.

Delegated work can actually change files. Upstream asks Codex for a write-capable sandbox but never checks that it got one, so on a host with no sandbox backend every --write run is silently read-only. This fork checks what Codex reports, refuses the run when it does not match what was asked for, and allows one narrow exception: it sends on-request instead of never when your own Codex config names an automated reviewer, and says in every output path that the reviewer, not you, approved the writes. Read-only runs always send never. See the Important block under /codex:rescue.

A review that runs no commands is not reported as clean. Codex's built-in reviewer cannot execute commands on some platforms, Windows among them. Upstream reports the empty result. This fork retries once with a locally collected diff embedded in the request, and says it did.

Windows works. Cancelling a background job kills the whole process tree instead of only the launcher; a path separator at the end of a quoted argument no longer escapes the next argument; the workspace root is resolved by walking for .git rather than by spawning git, which kept the session-end hook inside its timeout.

Prose that quotes a flag is prose. A flag counts as a flag only before the first word of your request. /codex:rescue explain why --danger-full-access is unsafe asks for an explanation and runs sandboxed.

Releases are checked against a fixed list. docs/acceptance.md holds twelve behaviours driven by hand against the real Codex CLI, plus the record of each run. CI fails the pull request that raises the version if the list has no record for the new version, and repeats the check on the tag.

The test suite is hermetic. Upstream's suite inherits plugin environment variables from the Claude Code shell it runs in, which writes fixture state into your real plugin data directory. The fix is ported from the open upstream pull request openai/codex-plugin-cc#456.

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.

If Codex's built-in reviewer runs no commands in your environment (a known Codex limitation on some platforms, including Windows), the plugin automatically retries once with a locally collected diff embedded directly in the review request instead of silently reporting a clean result.

Examples:

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

This command is read-only and will not perform any changes. When run in the background you can use /codex:status to check on the progress and /codex:cancel to cancel the ongoing task.

/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. If that focus text starts with -, put it after a literal -- so it isn't mistaken for an option.

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: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 and it's generally recommended to force the task to be in the background or move the agent to the background.

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. If your request text itself starts with - (for example a flag name you want Codex to look into), put it after a literal -- so it isn't mistaken for an option. A flag only counts as a flag before your request text: --danger-full-access written inside the request is part of what you are asking about, not a request to run without a sandbox.

Your request text does not go on the command line. Claude Code matches a Bash call against the caller's permission rules using the complete command text, so a request that merely quoted a flag or a command name your rules deny used to be denied before Codex ever ran. The subagent now writes your request to a file the plugin hands it, then runs task --prompt-file <path>, so only the command and its flags are matched. task deletes that file once the run finishes. A run that is refused before it starts, or that fails, leaves the file so the subagent can re-run the same request with whatever the error asked for; anything left behind is swept after an hour. Rules on flags still apply in full: a rule that denies --danger-full-access, for example, still stops a run that passes it.

Important

That file goes under the plugin's own data directory, which is outside your project, and Claude Code asks before a file write. On a default install it does prompt, checked by hand on 2026-09-21, so allowing that directory is part of setting the plugin up rather than a refinement. /codex:setup checks for the rule and prints the exact one for your machine. Claude Code matches file paths against Edit rules and ignores a path written on a Write rule, so the rule to add is:

{
  "permissions": {
    "allow": ["Edit(~/.claude/plugins/data/codex-vibecodedapps-codex/state/**)"]
  }
}

That directory is named for the plugin and for the marketplace under the name you added it with, so codex-vibecodedapps-codex is right for a marketplace added as vibecodedapps-codex and wrong if you added this repository under another name. Claude Code keeps the name the marketplace had when you added it, even after the marketplace itself is renamed. To see which one you have, list ~/.claude/plugins/data and take the entry beginning with codex-.

Without the rule each rescue stops for one approval. Asking for --background does not skip it: the write happens in the subagent before Codex is reached, so the same prompt appears either way, checked by hand on 2026-09-21.

The subagent holds the Write tool for this, and a tool grant covers every path, not just the one file it is told to write. Its instructions limit it to that path; nothing in the tool does. This grants it no reach it lacked, since it already held Bash and could write anywhere through that, but it is worth saying plainly.

Important

The trade is that your request text is no longer seen by Bash permission matching at all. If you relied on a deny rule matching words in a rescue request, it no longer fires. Write the rule against the flags instead, or deny the codex-companion.mjs task command outright.

You can still supply the file yourself with /codex:rescue --prompt-file <absolute-path>. A file you wrote is left on disk rather than deleted, and the run defaults to read-only, because the subagent does not read your file and so never assumes write access on your behalf. Add --write yourself, as a literal flag alongside --prompt-file, when the file's request needs Codex to edit the workspace.

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
/codex:rescue --prompt-file /Users/you/task.md

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 chooses its own defaults.
• 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

Important

Read-only runs (review, adversarial-review, and task without --write) always tell Codex never to ask for approval, so nothing in them can run outside the sandbox, whatever your Codex config says.

A --write run may let Codex approve its own requests to leave the sandbox, but only when your own Codex config names an automated reviewer (approvals_reviewer = "auto_review" in ~/.codex/config.toml). A project's .codex/config.toml cannot turn this on: a trusted project can set the same key, so the plugin checks which config file supplied it and ignores any source but yours, saying so in the progress log. The run's output, its progress log, and /codex:result all start with a warning when the escalation does apply. Without it a write run stays fully sandboxed.

Your own config is the only source that counts. A reviewer set for you by a system, MDM, or enterprise-managed config is ignored as well, which matters on a centrally managed Windows machine: --write cannot escalate there at all, so a write run needs either the same key in your own config or --danger-full-access. That is deliberate. The plugin cannot tell an administrator's config from a repository's by trust alone, and the safe answer for the machines that cannot write is a clear refusal rather than a silent escalation.

On Windows, codex-cli 0.155.1 has no sandbox backend at all (codex doctor reports sandbox backend disabled), so Codex keeps every thread read-only and can only write by asking for approval. A --write run there works only with an automated reviewer configured, and every write in it is approved by that reviewer, not by you, outside any sandbox. Without one the run stops with an error that names the choice: configure the reviewer, use --danger-full-access, or drop --write.

That allowance is tied to the host, not to the platform: before letting a read-only thread stand in for a write one, the plugin runs codex doctor and proceeds only when it reports the sandbox backend disabled. On a host that has a backend, a thread that came back read-only stops the run.

That check is coupled to one line of human-readable Codex output, the sandbox backend disabled line as codex doctor prints it on codex-cli 0.155.1. A Codex release that rewords or drops that line makes the check read the host as having a backend, and every --write run on a host that has none then refuses. It fails closed, never open, so an upgrade can cost you writes but cannot quietly grant them. If --write starts refusing after a Codex upgrade, run codex doctor and compare its sandbox section against the pattern in plugins/codex/scripts/lib/codex.mjs; --danger-full-access still works meanwhile.

/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

Use it to:

• check progress on background work
• see the latest completed job
• confirm whether a task is still running

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

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

Start Something Long-Running

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

Then check in with:

/codex:status
/codex:result

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

If you want to change the default reasoning effort or the default model that gets used by the plugin, you can define that inside your user-level or project-level config.toml. For example to always use gpt-5.4-mini on high for a specific project you can add the following to a .codex/config.toml file at the root of the directory you started Claude in:

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

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.

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

How is a release checked before it ships?

Against a fixed list of behaviours, driven by hand on a real machine rather than by reading the code for defects. The list, and the record of the last run, are in docs/acceptance.md.

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.