Codex Plugin for Claude Code: Install, Configure, Avoid Review Loops

Anyone who has run two coding agents side by side knows the routine. One terminal plans, the other reviews, and you sit between them copying text back and forth like a clipboard with opinions. Try to automate the conversation and the two start arguing over commas, and the session you meant to wrap up before lunch is still rewriting the same heading at four in the afternoon.

OpenAI's official plugin for Claude Code, codex-plugin-cc, removes most of that copying. It lets you call Codex reviews, task delegation and session transfer from inside Claude Code. Getting there is quick: put the Codex CLI on the machine, register OpenAI's marketplace in Claude Code, install the plugin, reload, and finish with the setup command. For the opposite arrangement, with Claude running as a guest inside Codex, there's a separate reverse plugin with its own install path. In both cases the sensible order is to share project instructions first and add bounded review and handoff rules before automating any loop.

The gain comes from a shorter handoff and not from smarter models. A repository that has one host terminal, with the guest agent running a review on its own, saves the human from shuttling every hunk of a diff between windows. The details below come from the plugins' documentation and community write-ups, and commands or model names may have changed since they were collected, so check them against the current READMEs before relying on them.

Choose the direction before installing anything

Picture getting into a car where two navigation units wake up together. One prefers the highway and the other the side streets, and neither waits for you to name a driver. Leave the driveway without deciding who calls the next turn and you end up stuck while both screens talk over each other.

The root issue is the host. The Codex plugin for Claude Code acts as an extra navigator, not an extra steering wheel, so settle which terminal drives before the first install command goes in.

Two routes exist, and each deserves its own procedure. A $cc: command doesn't belong in a Claude Code session, and a /plugin command pasted into Codex won't conjure the same plugin.

Official route: Codex inside Claude Code

This is OpenAI's own product for the purpose, codex-plugin-cc. Claude Code remains the workspace, and Codex joins as a visiting agent that can review code, challenge a design, take over a fix, run background jobs and carry a session across.

A plugin marketplace is simply the registry Claude Code consults to find plugins it can install. The sequence is to add OpenAI's marketplace, install codex@openai-codex, reload, and run /codex:setup. The plugin talks to your local Codex CLI and the Codex app server, and it doesn't start a separate cloud runtime of its own. Choose this route when Claude Code is already where you plan, search and steer. When a blog post and the repository README disagree, the README wins.

Reverse route: Claude inside Codex

Sendbird's cc-plugin-codex works the other way round. Codex hosts, and Claude Code is called in as a guest, normally through a new non-interactive claude -p subprocess per task. Installation happens inside Codex:

codex plugin marketplace add sendbird/codex-marketplace
codex plugin add cc@sendbird
$cc:setup

There's an idempotent helper, npx cc-plugin-codex install, that can be re-run for updates. $cc:setup checks hooks, cache trust and writable paths, and the reverse hooks also need hooks = true under [features] in ~/.codex/config.toml.

A third, unofficial option exists too: a community marketplace (yanchuk/claude-plugin-codex) with a $claude setup command. Treat it as community software and don't mix it up with OpenAI's plugin.

If what you want is a verdict on which product is better, that's a different comparison, and the discussion here stays on wiring. In short, the decision comes down to who is host, who is guest, and which install entry you're allowed to type.

Installing the official plugin inside Claude Code

The rest of this section follows the official route unless a heading says reverse. Brand comparisons, VS Code and Cursor are separate jobs, and the CLI itself, including platform installers and first-run sandbox flags, has its own install documentation.

Things will fail if Node.js is older than 18.18, if Codex isn't authenticated on the machine, or if you skip the reload and then conclude the plugin is broken.

Confirm the documented requirements

The official plugin needs Node.js 18.18 or newer. Sendbird's reverse plugin asks only for Node.js 18+, but anyone on the official route has to meet the higher bar. You also need a functioning local Codex CLI and a way to pay for it, which means a ChatGPT plan (the free one counts, per the upstream README) or an OpenAI API key. Claude Code brings its own requirement, either an Anthropic API key or a Claude Pro or Max plan. That makes two products and two bills, and the plugin doesn't combine them.

If the CLI is missing, install it:

npm install -g @openai/codex

Then authenticate through the documented Claude Code flow:

!codex login

Avoid mirror sites and third-party executable listings. The legitimate packages are the GitHub repository and the scoped npm CLI. And if your daily tool is an IDE sidebar and not Claude Code, you're dealing with a different host that has its own instructions.

Add the marketplace, install, reload, set up

Installing the official plugin takes four slash commands. A slash command is a /command entered in the Claude Code session and not a binary on your shell path. Run them in this order:

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

/reload-plugins refreshes the active plugin list, and skipping it can leave you with a successful install whose commands still appear missing. /codex:setup confirms that Codex is authenticated and, when the CLI isn't there, can propose installing the global @openai/codex package with npm. That's the whole official install. Most of the trouble people blame on the plugin comes from the steps around it.

Configure Codex for the project and not just the machine

A global install gives you commands. It doesn't tell Codex how a particular repository wants to be treated. User defaults and project overrides live in different files, and the project file loads only when the project is trusted.

A common slip is editing the user file to set a project's model, then wondering why a second repository inherited it. The inheritance is the design: that edit configured the machine, not the tree.

User settings versus trusted-project overrides

User-level configuration lives in ~/.codex/config.toml, the home-directory file Codex reads for every project. Overrides for a trusted project live in .codex/config.toml at the repository root. "Trusted" refers to Codex's project-trust flag: overrides load only if the directory is marked as trusted, and an untrusted tree ignores the local file. That's a safety boundary and not a bug, so when the project file seems not to load, check trust before debugging the TOML.

A reasonable split keeps secrets and default caution in the user file and puts repository-specific model and sandbox choices in the project file once the tree is trusted.

Model and reasoning behavior

Two keys matter here, model and model_reasoning_effort. The upstream README illustrates a project override like this:

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

Treat those values as examples that go stale. Model tags change quickly, and a string seen in a screenshot can be out of date a week later. Copy the keys, then recheck the values against current documentation before committing them to a repo. The plugin also accepts the shorthand spark, which maps to gpt-5.3-codex-spark; that mapping is documented but equally perishable, and if a later README drops it, believe the README.

model_reasoning_effort = "high" isn't a free quality slider, because higher effort burns more tokens on every turn. Save it for a design challenge or a nasty test failure and don't leave it on for a one-line rename.

Approvals and sandboxing

A third-party ShakaCode guide documents interactive overrides and environment keys that the official plugin README doesn't emphasize, so regard them as third-party guidance. approval_policy controls when Codex asks before acting, with untrusted and on-request as the values quoted. sandbox_mode limits what the process is allowed to touch, and the quoted options are read-only, workspace-write and danger-full-access.

approval_policy = "untrusted"
sandbox_mode = "workspace-write"

In the cited guide this is the standard profile for feature work: Codex may write inside the workspace but still asks before acting, as if the tree were only partly trusted. Reserve danger-full-access for test runners and build scripts you already trust, and never use it for a first look at an unfamiliar repo.

On the CLI, codex --auto-edit still prompts before shell execution, while codex --full-auto runs fully sandboxed with no prompts at all. The flags change prompting behavior and aren't synonyms, so don't reach for --full-auto just because it sounds decisive.

People often install a second plugin so they won't miss a feature, when the missing piece was a host decision that has to be made before the first slash command.

One source of project truth for both agents

Two agents on one tree with no shared instructions will invent two house styles by Thursday. Expect duplicated lint rules, duplicated test commands, and a review that undoes a convention the other agent had only just put back. Codex takes its repository rules from AGENTS.md, a Markdown file, and CLAUDE.md is the matching file for Claude Code. What you need is a policy for how the two relate, since nothing keeps them aligned unless someone makes it so.

The best-documented overview of the options is ShakaCode's claude-code-with-codex.md. It's dated on model names, so rely on it for file strategy and not for default model tags.

Reference a single instruction file

Put build commands, architecture notes and conventions in AGENTS.md, and turn CLAUDE.md into a pointer:

# Project Instructions
See @AGENTS.md for build commands, architecture, and conventions.

Two files remain, and Claude-specific notes can still sit under the pointer. The cost is upkeep, since forgetting to update the pointer leaves Claude following a stub. Codex can also be told to fall back when AGENTS.md is missing, via ~/.codex/config.toml:

project_doc_fallback_filenames = ["CLAUDE.md", "COPILOT.md"]

That's a read path and not a merge. Codex will look for those filenames, but it won't blend three files into one policy.

Symlink the universal rules

The quick version is a single command:

ln -s AGENTS.md CLAUDE.md

One inode, two names, so universal rules stay identical. The trade-off is real, though: you can't keep tool-specific directives apart, because there's no longer a second file. If Claude needs a hook that Codex should never see, a symlink can't express that.

Keep a shared core plus tool-specific additions

Rules that must be identical, such as the test command, lint settings and "don't rewrite formatting," belong in AGENTS.md, while Claude-only or Codex-only notes go in CLAUDE.md. It's the mature option and takes deliberate maintenance, which is why teams skip it and then blame the models for drifting.

If both agents will edit at once, shared instructions aren't enough. Isolate their working trees, with git worktrees being the usual tool, so they don't fight over one index. Simultaneous writes to a single checkout produce merge conflicts that neither agent caused on purpose.

Reviews, challenges, rescues and background work

With the plugin loaded, the temptation is to automate everything. The better habit is to use the smallest command that fits the job, since a read-only review isn't implementation and implementation isn't a design argument.

Plain review or adversarial review

/codex:review kicks off a read-only correctness check of local uncommitted changes or of a specified base. It accepts --base <ref>, --wait and --background, and it never writes files.

/codex:review --background

/codex:adversarial-review is a steerable design challenge that questions decisions, and free text can follow the flags.

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

On the reverse route the equivalents are $cc:review and $cc:adversarial-review, which do the same jobs under a different host. Don't mix the prefixes. A review that only nitpicks import order isn't a review, so write the functional question into the command, and if you can't state the question, you aren't ready to spend a reasoning turn.

Handing off a fix with rescue

/codex:rescue passes the implementation work to the plugin's subagent codex:codex-rescue, and unlike the review commands it changes files. Its flags include --background, --wait, --resume and --fresh.

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

The reverse twin is $cc:rescue. Keep the request narrow, because "make it better" earns you a rewrite you never wanted and a review loop you can't stop.

Tracking and controlling background jobs

"Background" here means the plugin job keeps running while you continue using Claude Code. It isn't a second checkout, and it's no promise that the work has finished.

/codex:status
/codex:result
/codex:cancel

/codex:status reports the state of background tasks, /codex:result shows their output and /codex:cancel stops them. Poll deliberately and don't read silence as success. The reverse plugin offers the matching three as $cc:status, $cc:result and $cc:cancel, and once more the host decides the prefix.

Transferring context and building a bounded handoff loop

A review in Claude Code isn't the same as a Codex session that can see the earlier reasoning, and when a debugging thread is already long, copy-paste is how the plot gets lost. /codex:transfer is the documented answer. Perfect state sync isn't on offer. What you get is a persistent Codex thread and a printed resume command, so the conversation crosses between the two without a human acting as the cable again.

Resuming in Codex after a transfer

/codex:transfer looks for the source transcript under ~/.claude/projects, and if the JSONL file isn't there, transfer can't invent it. What it prints is meant to be run in the Codex app or TUI:

codex resume <session-id>

Use the session ID the command emits, never a made-up one and never a pasted ChatGPT conversation URL.

Plan, implement, review, hand back

The loop that actually holds up is dull:

1. Plan in Claude Code and write the acceptance line first.
2. Implement, either in Claude Code or through /codex:rescue when the patch is bounded.
3. Review with /codex:review or /codex:adversarial-review, one at a time.
4. Return control, so a person applies, rejects or escalates.

The path has to end. A circle that always comes back to "one more pass" turns the gate into a furnace.

Stopping the endless review loop: a conflict and budget protocol

The feature meant to raise quality can burn through the budget over matters of taste. Running /codex:setup --enable-review-gate adds a local Stop hook, meaning a hook at the end of a turn: once Claude tries to wrap up, Codex is asked to check the result before the turn is allowed to close. If Codex finds problems, Claude is blocked so it can deal with them. With nobody watching, that circular loop can use up tokens fast. The official README cautions about this, yet it offers no budget protocol.

The three-iteration cap below is editorial guidance built on that gap and not an official plugin feature. There's no --max-iterations 3 flag to look for.

Define functional acceptance first

Write the list of blockers before anyone reviews, and keep it functional: tests that must pass, behavior that must not regress, and security or data issues that count as automatic rejects. Formatting, comment voice and heading level aren't blockers unless the repo's instruction file already forbids them. Let style into the gate and two agents will spend three turns agreeing to disagree about an H2.

One cautionary case: with the review gate enabled on a docs-only commit, the two agents debated whether a heading should be H2 or H3 until the session was killed, even though the page was already correct. With no definition of done, the gate made one up. Store the checklist in AGENTS.md, where both agents see identical rules. Restating it in the review command is fine, but a vague request like "make it cleaner" invites a rewrite.

Cap iterations and force a human decision

Limit yourself to three review-and-fix rounds per change:

• Iteration 1: functional blockers only.
• Iteration 2: whatever blockers remain, with no new style nits.
• Iteration 3: the last pass, and then stop.

After three, a person decides whether to merge, revert or rewrite the spec, and the agents don't get to vote again. Community threads about tmux wrappers and custom scripts count as experimental evidence and not as a second official path, so treat those scripts as someone else's workshop and not as commands from OpenAI.

Stop when nothing net has changed

Sendbird's reverse plugin takes a fingerprint of the working tree and leaves out the end-of-turn review whenever the previous Codex turn changed nothing net. That safeguard is documented for the reverse route, and upstream's gate doesn't advertise the same skip. On the official route you're the fingerprint: if git status is clean, skip another review, and if the last turn changed only comments, ask whether comments were on the acceptance list and stop if they weren't.

Wait to automate the gate until a single manual review has cleared the checklist. Turn on --enable-review-gate last and never first.

Troubleshooting by route, auth, trust and stale tasks

Diagnose the route before reinstalling anything. Failures on the official upstream path and failures of the reverse plugin's hooks look alike in a frustrated chat message and aren't the same system. Reinstalling is almost never the first check.

The official upstream path

• Plugin commands unavailable: run /reload-plugins. If they're still missing, confirm /plugin install codex@openai-codex actually finished, then run /codex:setup.
• Codex can't authenticate: type !codex login as the Claude Code flow describes. The plugin reads local auth state, and a logged-in ChatGPT browser tab isn't a logged-in CLI.
• Project overrides ignored: check that the project is trusted, and that the edit went into .codex/config.toml at the repo root and not just the home-directory file.
• Transfer can't find the transcript: the JSONL has to live under ~/.claude/projects, and a session that never wrote there can't be transferred. Start a real Claude Code project session first.
• Stale background work: use /codex:status, then /codex:result or /codex:cancel, and don't launch a second rescue just because the first went quiet.
• Node version errors: the plugin needs 18.18 or newer, so run node -v before opening an issue.

Reverse-plugin hooks and cache trust

If reverse hooks don't run, set hooks = true under [features] in ~/.codex/config.toml. If reverse setup looks incomplete, run $cc:setup, which is meant to confirm hooks, trust caches and writable paths. For the community plugin, $claude setup is that project's own check, and since it's unofficial, its failures shouldn't be filed against openai/codex-plugin-cc. Windows support on Sendbird's path is labeled experimental in its repo, so a WSL workspace is the better choice if the reverse plugin is the goal.

Quick answers to the usual questions

Is there one right way to combine them? Not really. The first decision is which tool hosts the session. With Claude Code as host, the OpenAI plugin plus shared instruction files and short slash-command tasks covers it. With Codex as host, Sendbird's reverse plugin and its $cc: prefix do the same job from the other side. Keep the two procedures apart, and keep both agents out of the same files at the same moment.

What exactly gets typed to install the official plugin? Four lines in the Claude Code prompt, in order: the marketplace add for openai/codex-plugin-cc, the install of codex@openai-codex, a plugin reload, and /codex:setup. If the Codex CLI isn't on the machine yet, setup can offer to fetch it, or you can install @openai/codex yourself beforehand and sign in with !codex login.

Does the plugin bring its own Codex backend? No. Everything is routed to the Codex CLI and app server already on your computer, so the same login and the same ChatGPT plan or API key apply. Whatever access that CLI needed, it still needs.

What's the cleanest way to give both agents the same rules? Three patterns work: let CLAUDE.md point at AGENTS.md, symlink one onto the other, or put the shared core in AGENTS.md and leave tool-specific extras in CLAUDE.md. A fallback-filename setting in the user config lets Codex read Claude's file when AGENTS.md is absent. The symlink is the fastest, at the price of dropping tool-specific files.

Where does a per-project model choice go? In a .codex/config.toml at the root of a project you've marked trusted, using the model and model_reasoning_effort keys. Sample values from the docs, like gpt-5.4-mini and high, age fast, so check them. An untrusted project quietly falls back to your user defaults.

What does the review gate do? Enabling it registers a local Stop hook. When Claude tries to end a turn, Codex checks the work first, and any problems found block the turn so Claude can fix them. Unsupervised, that can eat tokens. The reverse plugin can skip a pass when nothing in the working tree changed, but that is its own behavior and not something upstream promises.

How does a session move across? Run /codex:transfer in Claude Code. It turns the transcript saved under ~/.claude/projects into a persistent Codex thread and prints a codex resume line with the session ID, which you then run in the Codex app or TUI. No transcript in that folder means nothing to transfer.

How do I stop the two from burning tokens? Define functional-only acceptance criteria up front, allow three review-and-fix rounds, then involve a human. Switch the gate on only after a manual review has passed. If git status shows a clean tree, or the last turn touched only style nobody listed as a blocker, end the loop yourself.

A safe first experiment

Pick one repository you already understand and one failing test or one small change to review, and commit or stash first. Install only the official route and run /codex:review on that change. Read the result, then apply or reject it yourself, and leave --enable-review-gate off on the first afternoon.

If the review proves useful, share AGENTS.md next and try a single /codex:transfer on a real debugging thread. That's the whole experiment. Model names will keep changing, but the host decision and the stop condition will stay relevant. What remains unclear is how long teams will put up with two bills and two instruction files before someone asks for a single vendor again. For now the sensible version of this stack is a doorbell with house rules and not a roommate with a key.