Claude Code Plugin for Codex

Run Claude Code reviews, rescue tasks, transfers, and tracked background work from inside Codex.

cc-plugin-codex runs inside Codex and lets you use Claude Code and Claude models for review, rescue, transfer, and tracked background workflows.

Quick Start · Commands · Peer Workflows · Background Jobs · Review Gate · vs Upstream · Issues

---

What Is This?

cc-plugin-codex turns Codex into a host for Claude Code work. Codex stays in charge of the thread. Claude Code does the review and rescue work.

You get eleven commands, including $cc:design and $cc:research, that launch tracked Claude Code work, compare independent Codex and Claude evidence, transfer transcripts, manage lifecycle and ownership, and surface results back into Codex.

That includes:

• Built-in Codex subagent orchestration for rescue and background review flows
• Session-scoped tracked jobs with status, result, and cancel commands
• Durable peer design/research workflows with independent evidence, failed-only retry, and cross-session continuation
• Background completion nudges that steer you to the right $cc:result <job-id>
• An optional stop-time review gate
• GitHub CI coverage on Windows, macOS, and Linux

It follows the shape of openai/codex-plugin-cc but runs in the opposite direction.

Quick Start

1. Install

Install the fork release from the CBEPX marketplace snapshot:

codex plugin marketplace add CBEPX/cc-plugin-codex --ref v1.7.3
codex plugin add cc@cbepx

Then run $cc:setup once inside Codex.

cc-plugin-codex uses Codex native plugin hooks. Hook commands enter through a small launcher under $PLUGIN_DATA; it resolves the current valid version from Codex's plugin cache, so an already-running session does not keep executing a deleted cache path.

The optional npx helper can install this fork release and enable the required Codex feature gates:

CC_PLUGIN_CODEX_MARKETPLACE_NAME=cbepx \
CC_PLUGIN_CODEX_MARKETPLACE_SOURCE=CBEPX/cc-plugin-codex \
CC_PLUGIN_CODEX_MARKETPLACE_REF=v1.7.3 \
npx -y https://github.com/CBEPX/cc-plugin-codex/releases/download/v1.7.3/cc-plugin-codex-1.7.3.tgz install

On Windows, prefer the marketplace path or the npx helper. The shell-script helper below is POSIX-only. Codex CLI's official guidance still treats Windows support as experimental and recommends a WSL workspace for the best Codex experience. Claude Code supports both native Windows and WSL.

If install/update/uninstall reports an invalid global hooks.json while a legacy cc install is present, repair that JSON before retrying. To continue without touching risky legacy hook files, set CC_PLUGIN_CODEX_SKIP_LEGACY_CLEANUP=1; uninstall still removes official plugin config/cache state but deliberately leaves the legacy files for manual repair. An explicit Codex RPC permission/auth refusal remains fail-closed; use CC_PLUGIN_CODEX_IGNORE_UNINSTALL_RPC=1 only when you intentionally want local uninstall cleanup despite that refusal.

Prerequisites: Node.js 18+, Codex with hook support, and claude CLI installed and authenticated. If you don't have the Claude CLI yet:

npm install -g @anthropic-ai/claude-code && claude auth login

2. Verify

Open Codex and run:

$cc:setup

All checks should pass. If any fail, $cc:setup tells you what to fix.

3. Try It

$cc:review --background

That launches a Claude Code review from a Codex-managed background flow. You can check on it immediately:

$cc:status
$cc:result

When it finishes, Codex should nudge you toward the right result. If not, $cc:status and $cc:result are always the fallback.

Commands

Command	What It Does
$cc:review	Read-only Claude Code review of your changes
$cc:adversarial-review	Design-challenging review — questions approach, tradeoffs, hidden assumptions
$cc:rescue	Hand a task to Claude Code — bugs, fixes, investigations, follow-ups
$cc:design	Compare technical alternatives with independent Codex and Claude evidence
$cc:research	Investigate a repository question with independent Codex and Claude evidence
$cc:transfer	Import the current Claude transcript into a resumable Codex thread
$cc:status	List jobs and aggregate peer workflows, or inspect one ID
$cc:result	Open a job result or peer checkpoint/final result
$cc:cancel	Cancel an active job or peer workflow
$cc:mcp-diagnose	Explain which Claude MCP tools would be available to reviews
$cc:setup	Verify installation, auth, hooks, and review gate

Quick routing rule:

• Use $cc:review for straightforward correctness review of the current diff.
• Use $cc:adversarial-review for riskier config/template/migration/design changes, or whenever you want stronger challenge on assumptions and tradeoffs.
• Use $cc:rescue when you want Claude Code to investigate, validate by changing code, or actually fix/implement something.
• Use $cc:design or $cc:research when the decision benefits from two independent read-only evidence paths before synthesis.

$cc:review

Standard read-only review of your current work.

$cc:review                          # review uncommitted changes (default: opus + xhigh effort)
$cc:review --base main              # review branch vs main
$cc:review --scope branch           # explicitly compare branch tip to base
$cc:review --background             # run in background, check with $cc:status later
$cc:review --model sonnet           # switch to sonnet (defaults to high effort)
$cc:review --model fable --effort xhigh  # use Fable explicitly for hardest reviews
$cc:review --model opus --effort high   # opus with a lighter effort
$cc:review --user-mcp-tool mcp__context7__resolve-library-id

Flags: --base <ref>, --scope <auto|working-tree|branch>, --wait, --background, --model <model>, --effort <low|medium|high|xhigh|max>, --user-mcp-tool <mcp__server__tool>, --allow-project-mcp-servers

Defaults: model opus is passed to Claude Code as its native alias with xhigh effort. sonnet is passed through with high effort; haiku and fable are passed through with no default effort setting. Claude Code resolves aliases to the current model for the active provider and account (for example, Opus 5). Pass a full model ID to pin a version; for older pinned IDs, pass --effort explicitly instead of inheriting a current-family default.

Fable 5.1 (claude-fable-5-1) has a native 1M context window and requires Claude Code 2.1.257 or newer. The bare fable alias remains floating and may still resolve to Fable 5 behind Claude Apps Gateway; use the full model ID when Fable 5.1 is required. No [1m] suffix or hidden Fable effort default is added. See Claude Code's model configuration.

JSON task and review results keep requestedModel as the forwarded alias or full ID, report finalModel from Claude's terminal result, and expose the terminal contextWindow reported in modelUsage (null when Claude does not provide it). The plugin does not infer a context limit from a floating alias.

Scope auto (the default) inspects git status and chooses between working-tree and branch automatically.

In foreground, review returns the result directly. In background, the plugin uses a Codex built-in subagent, tracks the review as a job, and nudges you to open the result when it completes.

If the diff is too large to inline safely, the review prompt falls back to concise status/stat context and tells Claude to inspect the diff directly with read-only git diff commands instead of failing the run.

By default, review runs with only the bundled read-only git MCP. Repeat --user-mcp-tool <mcp__server__tool> to opt in specific Claude MCP tools from your user-scope Claude config for a run. Opted-in user MCP tools run as external Claude MCP processes and are auto-approved for that review, so use only trusted tools when reviewing untrusted diffs. Eligibility is based on the server's readOnlyHint declaration or the plugin's audited read-only registry; it is not an OS-enforced sandbox. A destructiveHint declaration is always vetoed. Project .mcp.json server definitions are ignored unless you also pass --allow-project-mcp-servers.

$cc:mcp-diagnose

Shows which Claude MCP servers the plugin can see for review commands, which requested tools would be allowed, and why a tool is missing.

$cc:mcp-diagnose --user-mcp-tool mcp__context7__resolve-library-id
$cc:mcp-diagnose --allow-project-mcp-servers --user-mcp-tool mcp__localdocs__search

The diagnostic actively starts/probes every configured server in scope (or sends HTTP initialize and tool-list requests), with a five-second absolute deadline per server. Treat that discovery as potentially side-effecting. The output lists server names and config sources only; it does not print raw MCP server configs or secrets. Once a peer workflow freezes its selected manifest, later turn revalidation probes only those selected servers.

Peer design and research

$cc:design and $cc:research start a durable read-only workflow with exactly two independent branches: one Codex reasoning worker and one Claude forwarder. The initial branches receive the same frozen brief and cannot read each other's memo before sealing their own evidence.

$cc:design compare the queue ownership alternatives
$cc:research trace how cancellation state reaches the public CLI
$cc:status <workflow-id>
$cc:result <workflow-id>
$cc:design --continue <workflow-id> optional feedback
$cc:design --retry <workflow-id>

New workflows default to Claude fable with opus fallback and inherited Codex model at xhigh effort. Use --model, --fallback-model, --effort, --codex-model, or --codex-effort to override them. Repeat --user-mcp-tool <mcp__server__tool> for explicitly trusted eligible tools; automatic selection is limited to the smallest relevant eligible set exposed to the active Codex turn. Eligibility records whether trust came from readOnlyHint or the audited registry, but does not independently enforce server behavior. Project MCP servers still require --allow-project-mcp-servers.

The audited annotationless Brave allowlist contains exactly mcp__brave-search__brave_web_search and mcp__brave-search__brave_llm_context; other Brave IDs are not eligible through it. A Brave event counts as Claude web evidence only when that exact ID is also in the workflow's frozen selected-tool manifest. The manifest records the selected ID and trust basis, not the provider's behavior: an @latest Brave server can still change a tool behind the same ID. Pin a server version when that drift is unacceptable.

Selected Brave MCP servers are external trusted processes/services, not an OS sandbox. Their query or context input can disclose the brief and research terms to the provider; do not send secrets or sensitive material through either tool. The workflow never persists raw MCP configuration or credentials, but that does not remove this upstream disclosure risk.

The stored and rendered workflow shows independent branch states, requested/final models and fallback events, source/tool evidence counts, selected public tool IDs and reasons, checkpoint or final result, and the exact continue/retry command. Raw MCP configuration, environment variables, headers, and credentials are never persisted or rendered. Claude receives no Bash, write, or Agent capability, and only selected MCP servers enter its strict runtime config. Peer turns also require the platform filesystem sandbox, deny unsandboxed commands and reads of canonical Codex/Claude state, persist no Claude transcript, and expose only content-free phase/tool/model-fallback progress before reveal. Native Windows peer execution is unsupported and isolation failures stop with PEER_ISOLATION_UNAVAILABLE.

Attempt leases are single-use secrets sent through stdin, while durable state keeps only their digests. A Claude-first memo remains process-local until Codex seals its independent memo. That wait has one absolute 30-minute deadline; retry keeps a committed waiter only while its current linked job is alive, rotates only unfinished reservations, and never rewrites completed payloads. A lost, terminal, or reaped worker becomes retryable, while unresolved process cancellation stays terminal as cancel_failed.

At the checkpoint, inspect the aggregate result and either continue with feedback or retry only failed/missing work. Continuation may run from a new Codex session: ownership is rebound explicitly, and critique starts a fresh ephemeral Claude turn from the frozen brief, memos, and feedback. SessionEnd marks unfinished work retryable after identity-checked linked-process cleanup; unresolved cancellation remains cancel_failed.

$cc:adversarial-review

Same as $cc:review, but steers Claude to challenge the implementation — tradeoffs, alternative approaches, hidden assumptions.

$cc:adversarial-review
$cc:adversarial-review --background question the retry and rollback strategy
$cc:adversarial-review --base main challenge the caching design
$cc:adversarial-review --user-mcp-tool mcp__context7__resolve-library-id focus on API parity

Accepts the same flags as $cc:review, plus free-text focus after flags to steer the review.

Background adversarial review uses the same tracked built-in subagent pattern as $cc:review.

$cc:rescue

Hand a task to Claude Code. This is the main way to delegate real work — bug fixes, investigations, refactors.

$cc:rescue investigate why the tests started failing
$cc:rescue fix the failing test with the smallest safe patch
$cc:rescue --resume apply the top fix from the last run
$cc:rescue --background investigate the regression
$cc:rescue --model sonnet --effort medium investigate the flaky test

Flags:

Flag	Description
--background	Run in background; check later with $cc:status
--wait	Run in foreground
--resume	Continue the most recent Claude Code task
--resume-last	Alias for --resume
--fresh	Force a new task (don't resume)
--write	Allow file edits (default)
--model <model>	Claude model (opus, sonnet, haiku, fable, or full ID; defaults to opus). Aliases are resolved by Claude Code; a full ID pins a version.
--effort <level>	Reasoning effort: low, medium, high, xhigh, max (default: xhigh for opus, high for sonnet, unset for haiku and fable)
--prompt-file <path>	Read task description from a file
--view-state on-terminal	Mark the foreground terminal outcome as viewed
--view-state defer	Leave the terminal outcome unread for later inspection
--wait-timeout-ms <ms>	Foreground observer timeout before returning a retrievable job
--timeout-ms <ms>	Deprecated alias for --wait-timeout-ms

Resume behavior: If you don't pass --resume or --fresh, rescue checks for a resumable Claude session and asks once whether to continue or start fresh. Your phrasing guides the recommendation — "continue the last run" → resume, "start over" → fresh.

Background rescue runs through a built-in Codex subagent. When the child finishes, the plugin tries to nudge the parent thread with the exact $cc:result <job-id> to open.

The forwarding subagent inherits the current Codex runtime model at medium effort. This avoids stale model pins, but it can cost more than the former mini-model forwarder.

$cc:transfer

Transfer the current Claude transcript into a persistent Codex thread and print a resume command.

$cc:transfer
$cc:transfer --source ~/.claude/projects/-Users-me-repo/session.jsonl

The SessionStart hook normally supplies the current transcript path automatically. --source is available as a manual override. Codex can import only Claude session JSONL files under ~/.claude/projects, and the command requires a Codex version with native external-agent session import support.

$cc:status

$cc:status                          # list jobs and aggregate peer workflows
$cc:status task-abc123              # detailed status for one job or workflow
$cc:status --all                    # include all workspace jobs, including workflow-linked jobs
$cc:status --wait task-abc123       # block until the job/workflow stops running

By default, $cc:status shows current-session jobs plus one aggregate row per owned peer workflow; workflow-linked implementation jobs are hidden. Use --all for the wider repository view and linked-job diagnostics.

$cc:result

$cc:result                          # open the latest job or workflow result for this session/repo
$cc:result task-abc123              # show job output or a workflow checkpoint/final result

When a job came from a built-in background child, the output can show both:

• the Claude Code session you can resume with claude --resume ...
• the Owning Codex session that owns the tracked job inside Codex

To reopen the Claude Code session directly:

claude --resume <session-id>

$cc:cancel

$cc:cancel task-abc123              # cancel a running job or peer workflow

Workflow cancellation targets only its linked work. A missing or unverifiable process identity remains visible as cancel_failed; the plugin does not turn that state into a successful cancellation.

$cc:setup

$cc:setup                           # verify everything
$cc:setup --check                   # read-only readiness check
$cc:setup --enable-review-gate      # turn on stop-time review gate
$cc:setup --disable-review-gate     # turn it off

Setup checks Claude Code availability, native plugin hook feature gates, and review-gate state. --check reports required repairs without changing config or hook trust. If Claude Code isn't installed, setup offers to install it. This is also the repair path for marketplace-installed copies of the plugin: $cc:setup installs or refreshes the stable hook launcher, confirms [features].hooks = true, then trusts this plugin's current native hook hashes.

Background Jobs

All review and rescue commands support --background. Background jobs are tracked per-session with full lifecycle management:

1. Queued → Running → Completed — jobs progress through states automatically.
2. Built-in subagent background flows — background rescue, review, and adversarial review use Codex-managed subagent turns rather than stuffing --background into the companion command itself.
3. Completion nudges — when a background built-in flow finishes, the plugin tries to nudge the parent thread with the right $cc:result <job-id>. Peer workflows notify only at an aggregate checkpoint, incomplete state, or final completion; linked jobs never produce duplicate nudges. If a nudge cannot surface cleanly, unread-result hooks are the backstop. The nudge is intentionally just a pointer. The actual stored result still opens through $cc:result.
4. Unread-result fallback — when you submit your next prompt after a finished unread job, Codex can remind you that a result is waiting and point you to $cc:status / $cc:result.
5. Session ownership — jobs stay attached to the user-facing parent Codex session even when a built-in rescue/review child does the actual work, so plain $cc:status, $cc:result, and resume-candidate detection still follow the parent thread.
6. Cleanup on exit — when your Codex session ends, any still-running detached jobs are terminated via PID identity validation, and stale reserved job markers are cleaned up over time.

Job inspection can also reconcile stale queued, running, or cancelling records. It only terminates an orphaned owned process after its recorded PID identity matches; healthy active jobs are left unchanged. $cc:result and JSON status access may additionally record that a terminal result was viewed.

Typical background flow:

$cc:rescue --background investigate the performance regression
# ... keep working ...
# Codex nudges with the exact result command when possible
$cc:result task-abc123

What “background” means here

• The parent Codex thread does not wait.
• The Claude companion command still runs in the foreground inside its own worker/subagent thread.
• For rescue and background review flows, the plugin prefers Codex built-in subagents and only uses job polling/status commands as the durable backstop.

Review Gate

The review gate is an optional stop-time hook. When enabled, pressing Ctrl+C in Codex triggers a Claude Code review of the last Codex response before the stop is accepted.

• Claude returns ALLOW: → stop proceeds normally.
• Claude returns BLOCK: → stop is rejected; Codex continues.

Caveats:

• Disabled by default. Enable with $cc:setup --enable-review-gate.
• Token cost. Every Ctrl+C triggers a Claude invocation. This can drain usage limits quickly if you stop often.
• 15-minute timeout. The gate has a hard timeout. If Claude doesn't respond, the stop is allowed.
• Skip-on-no-edits. The gate computes a working-tree fingerprint baseline and skips review when the last Codex turn made no net edits.
• Requires a recorded user turn. If the UserPromptSubmit hook did not record a baseline for this session, the gate skips review instead of reviewing unrelated or headless work.
• Not in nested sessions. Child sessions (e.g., rescue subagents) suppress the gate to avoid feedback loops.

Only enable when you're actively monitoring the session.

How This Differs From Upstream

	openai/codex-plugin-cc	This repository
Host	Claude Code hosts the plugin	Codex hosts the plugin
Commands	/codex:review, /codex:rescue, …	$cc:review, $cc:rescue, …
Runtime	Codex app-server + broker	Fresh claude -p subprocess per invocation
Review gate	Reviews previous Claude response	Reviews previous Codex response
Model flags	Codex model names and effort controls	Claude model names and effort values (low / medium / high / max)

Where This Goes Further

• Smart review gate — fingerprints the working tree and skips review when the last Codex turn made no net edits, avoiding unnecessary token spend.
• Nested-session awareness — suppresses stop-time review and unread-result prompts in child runs, keeping interactive hooks attached to the user-facing thread only.
• Tracked job ownership — background jobs track unread/viewed state and session ownership, with safe PID-validated cleanup on session exit.
• Built-in background notify — rescue and review flows can now wake the parent thread and point directly to $cc:result <job-id> instead of relying only on later polling.
• Unread-result nudges — completed background jobs are still surfaced in your next prompt as a reliable fallback.
• Idempotent installer — installs through Codex's marketplace/cache path and enables native hook feature gates. Safe to re-run for updates.

Install Variants

CBEPX fork marketplace (preferred for this fork)

Install from the fork's marketplace snapshot:

codex plugin marketplace add CBEPX/cc-plugin-codex --ref v1.7.3
codex plugin add cc@cbepx

Then run:

$cc:setup

Marketplace/plugin install places the plugin under Codex's plugin cache. $cc:setup verifies Claude Code, installs or refreshes the stable hook launcher, confirms [features].hooks = true, and trusts the current hooks/hooks.json hook hashes.

Upstream Sendbird build

This fork does not install from the upstream Sendbird marketplace. Use the CBEPX marketplace commands above when you want this fork.

npx helper

CC_PLUGIN_CODEX_MARKETPLACE_NAME=cbepx \
CC_PLUGIN_CODEX_MARKETPLACE_SOURCE=CBEPX/cc-plugin-codex \
CC_PLUGIN_CODEX_MARKETPLACE_REF=v1.7.3 \
npx -y https://github.com/CBEPX/cc-plugin-codex/releases/download/v1.7.3/cc-plugin-codex-1.7.3.tgz install

After install, run:

$cc:setup

The helper adds the configured marketplace, installs cc through Codex app-server, enables native hook feature gates, and removes stale global hook entries from older installs.

Shell script (POSIX-only)

Install the fork from the current CBEPX/cc-plugin-codex main branch:

curl -fsSL "https://raw.githubusercontent.com/CBEPX/cc-plugin-codex/main/scripts/install.sh" | bash

After install, run:

$cc:setup

Update

Re-run the fork marketplace install flow, pinned to the release you want:

codex plugin marketplace add CBEPX/cc-plugin-codex --ref v1.7.3
codex plugin add cc@cbepx

Uninstall

codex plugin remove cc@cbepx

Troubleshooting

$cc:setup reports Claude Code not found

npm install -g @anthropic-ai/claude-code
claude auth login

Commands not recognized in Codex Re-run install and restart Codex. This plugin expects Codex plugin support and no longer installs local skill-wrapper fallbacks.

Hooks not firing Check that hooks = true is set in ~/.codex/config.toml under [features]. Run $cc:setup to verify and auto-repair the stable launcher, feature gate, and this plugin's hook trust hashes, then restart Codex if the flag was just changed.

A background job finished but I did not get the result nudge Use:

$cc:status
$cc:result

The built-in notify path is best-effort. The tracked job store and unread hook remain the reliable fallback.

If you think the job may belong to an older session in the same repository, use:

$cc:status --all

If a finished result shows both a Claude Code session and an Owning Codex session, use the Claude Code session for claude --resume .... The owning session is there only to explain which Codex thread owns the tracked job.

Large review diff caused a failure or was omitted That is expected on very large diffs. The plugin now degrades to a compact review context and points Claude toward read-only git diff commands instead of trying to inline everything. If you want the full picture, run a narrower review such as:

$cc:review --base main
$cc:review --scope working-tree

Review gate draining tokens Disable it: $cc:setup --disable-review-gate. The gate fires on every Ctrl+C, which adds up.

Background jobs not cleaned up Jobs are terminated when the Codex session that owns them exits. If a session crashes without cleanup, use $cc:status and $cc:cancel <job-id> to clean up any leftovers.

Development

Run the normal project gate before publishing or opening a PR:

npm run check
npm run test:coverage

npm run check requires a working codex executable for its real E2E suite. Constrained local environments may opt out explicitly with CC_PLUGIN_ALLOW_E2E_SKIP=1 npm run check; CI never uses that opt-out. Coverage stays a separate instrumented run because npm run check already executes the full unit, integration, and Codex E2E suites. CI fails below 89% lines/statements, 79% branches, or 96% functions.

Mutation testing enforces the same pull-request profile used in CI:

npm run test:mutation:dry-run
npm run test:mutation
npm run test:mutation:force

test:mutation checks the critical parser contracts plus managed cleanup and installer orchestration. test:mutation:force runs all seven shards, matching the weekly/manual workflow. Scores below each configured break threshold fail the command, and reports are written under reports/mutation/. Use the force variant after changing only tests because command-runner incremental mode cannot reliably detect that. Do not mass-disable surviving mutants; improve the focused tests or use a // Stryker disable ...: reason comment only for an intentional equivalent mutant.

Mutation testing requires Node.js 20+ because Stryker 9 has a newer development-time engine requirement. The plugin runtime still supports the Node.js version listed in the prerequisites.

Planned follow-ups

• Reduce surviving mutants and timeout-only kills in the claude-cli and state shards by classifying equivalent mutants and replacing timeout-only detection with deterministic assertions where practical.
• Treat mandatory contextWindow persistence across JSON payloads as a separate versioned telemetry-contract change, with explicit nullability, backward compatibility, payload coverage, tests, and an appropriate semver release.

License

Apache-2.0 — see NOTICE for attribution.