cc-plugin-codex

---

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 seven commands ($cc:review, $cc:adversarial-review, $cc:rescue, $cc:status, $cc:result, $cc:cancel, $cc:setup) that launch tracked Claude Code work, 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
• Background completion nudges that steer you to the right $cc:result <job-id>
• An optional turn-end 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 from the Sendbird marketplace:

codex plugin marketplace add sendbird/codex-marketplace
codex plugin add cc@sendbird

Then install cc from the Sendbird marketplace inside Codex, and run $cc:setup once.

cc-plugin-codex uses Codex native plugin hooks. The active plugin copy lives under Codex's plugin cache, and hook commands resolve through $PLUGIN_ROOT; there is no separate local checkout install.

The optional npx helper runs the same marketplace/cache install path and enables the required Codex feature gates:

npx cc-plugin-codex install

On Windows, prefer the Sendbird 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.

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. If setup adds the marketplace-qualified plugin-data root and legacy migration roots to the writable-root list, restart Codex and rerun the same command; a requested review-gate toggle waits for that restart.

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:status	List running and recent Claude Code jobs, or inspect one job
$cc:result	Open the output of a finished job
$cc:cancel	Cancel an active background job
$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.

$cc:review

Standard read-only review of your current work.

$cc:review                          # review uncommitted changes (default: opus)
$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
$cc:review --model fable            # use Fable
$cc:review --model opus --effort xhigh  # explicitly raise opus effort

Flags: --base <ref>, --scope <auto|working-tree|branch>, --wait, --background, --model <model>, --effort <low|medium|high|xhigh|max>

Defaults: model opus, and no effort at all. After trimming surrounding whitespace, the friendly aliases fable, opus, sonnet, and haiku are matched case-insensitively and canonicalized to lowercase; every other --model value passes through unchanged for Claude Code to resolve, including full model IDs and provider-specific names. --effort is forwarded only when you pass it, so each model keeps whatever effort Claude Code defaults to. Claude Code owns which effort levels each model supports, so check /model rather than assuming a level applies everywhere.

Model discovery: run /model in Claude Code to see the models and effort levels available to your current account and provider, then pass the selected alias or full ID to this plugin. The plugin intentionally does not maintain a static model catalog, a per-model effort table, or force [1m]; Claude Code owns alias versions, supported effort levels, managed restrictions, provider routing, and extended-context eligibility.

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.

$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

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>	Any Claude Code model alias, full model ID, or provider-specific name; defaults to opus. Run /model in Claude Code to discover options available to your account and provider.
--effort <level>	Reasoning effort: low, medium, high, xhigh, max. Unset by default, so the model keeps Claude Code's own effort default. Claude Code owns which levels each model supports.
--prompt-file <path>	Read task description from a file

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.

$cc:status

$cc:status                          # list active and recent jobs
$cc:status task-abc123              # detailed status for one job
$cc:status --all                    # show all tracked jobs in this repository workspace
$cc:status --wait task-abc123       # block until job completes

By default, $cc:status shows jobs owned by the current Codex session. Use --all when you want the wider repository view across older or sibling sessions in the same workspace.

$cc:result

$cc:result                          # open the latest finished job for this session/repo
$cc:result task-abc123              # show finished job output

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

$cc:setup

$cc:setup                           # verify everything
$cc:setup --enable-review-gate      # turn on turn-end review gate
$cc:setup --disable-review-gate     # turn it off

Setup checks Claude Code availability, native plugin hook feature gates, and review-gate state. If Claude Code isn't installed, it offers to install it. This is also the repair path for marketplace-installed copies of the plugin: $cc:setup confirms [features].hooks = true, trusts this plugin's current native hook hashes, and allows sandboxed writes to Codex's injected marketplace-qualified plugin-data root plus the legacy roots needed for one-time migration. If those writable roots were just added, restart Codex and rerun setup before changing the review gate.

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>. If that 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.