CC for Codex

Use Codex as the primary engineer and bring in your local Claude Code CLI only when a second opinion, adversarial challenge, or isolated delegation is useful. CC for Codex also provides a full heavy-track workflow for planning, implementation, validation, and review from the Codex macOS app or CLI.

Created with GPT-6 Astra in Codex.

Logo and brand assets

See the workflow in action

Watch the 55-second workflow demo recorded in Codex:

https://github.com/user-attachments/assets/bdba3033-1279-4283-a587-0cc50fa43b2f

Download the original recording

See CC for Codex in the plugin browser — six Claude integration skills and starter prompts

Copy this into Codex

Paste this entire prompt into a Codex task in the macOS app or CLI. It installs the plugin, verifies the installed package and local Claude Code readiness, and performs one explicitly authorized read-only smoke test:

Install and verify CC for Codex from https://github.com/sanchitmonga22/cc-for-codex.

Do not modify project code, credentials, unrelated settings, or unrelated plugins. The only configuration changes authorized here are adding/upgrading this marketplace, installing this exact plugin, and appending CC for Codex's marked Codex-first blocks to the two global instruction files after their dry run passes. Use the local terminal only for this installation and verification.

1. Run `codex --version` and confirm the Codex CLI is available.
2. Inspect `codex plugin marketplace list --json`. Locate the entry named `cc-for-codex` and require its `marketplaceSource.source` to be `https://github.com/sanchitmonga22/cc-for-codex.git` (the same URL without `.git` is also equivalent). If it is absent, run `codex plugin marketplace add sanchitmonga22/cc-for-codex --ref main --json`. If the name exists with any other source, stop and ask me before changing it. If the source matches, run `codex plugin marketplace upgrade cc-for-codex --json`.
3. Inspect `codex plugin list --json`. If `cc-for-codex@cc-for-codex` is absent, run `codex plugin add cc-for-codex@cc-for-codex --json`. If it is installed below semver `0.2.0`, run `codex plugin remove cc-for-codex@cc-for-codex --json` and then reinstall it with the preceding `plugin add` command. Do not remove it when the installed version is already `0.2.0` or newer.
4. Inspect `codex plugin list --json` again. Require the exact plugin ID `cc-for-codex@cc-for-codex`, with `installed: true`, `enabled: true`, and version `0.2.0` or newer. Use only that entry's reported `source.path`; do not guess or search for a cache directory. Change directory to that exact path before the next steps.
5. From that verified source path, run `node scripts/install-global-workflow.mjs --check`, report the absolute targets, then run it with `--apply`. This required step may append only the marked blocks to global `CLAUDE.md` and `AGENTS.md`; if legacy role text is reported, stop and ask before using `--allow-conflicts`.
6. Run `scripts/cc-for-codex doctor --json`. Confirm that Claude Code is installed, authenticated, and reports the required guarded capabilities. Do not print email addresses, tokens, organization IDs, settings, environment variables, or unrelated plugin details.
7. I authorize exactly one minimal Claude model request for a live read-only smoke test, which may count against my Anthropic plan or API billing. Run the verified source path's runner with: `ask --model haiku --max-turns 1 --text-only --prompt "Reply with exactly: CC for Codex is connected."` Do not enable native mode, MCP, Chrome, shell tools, edits, background execution, or dangerous permissions.
8. Require a successful exit and the exact response `CC for Codex is connected.`. Report each check separately as installed, locally configured, locally ready, and live-proven. If any step fails, stop and show the exact failing command and a redacted error; do not weaken safeguards or silently install other software.
9. Remind me to start a new Codex task so the newly installed skills load. In that new task, the reusable check is: `Use $claude-verify to verify CC for Codex.`

The final live check consumes one small Claude request. Skip step 7 if you want installation and local diagnostics only; step 6 is the local readiness check.

This is the reciprocal companion to OpenAI's official Codex plugin for Claude Code: that project brings Codex into Claude Code; this project brings a user-installed Claude Code CLI into Codex.

[!IMPORTANT]
CC for Codex is an unofficial, independent open-source project. It is not affiliated with, endorsed by, or published by Anthropic or OpenAI. It invokes your own locally installed and authenticated claude executable; Claude usage follows your Anthropic plan, provider, and billing.

Install in under a minute

Prerequisites: a current Codex CLI / Codex app and an installed, authenticated Claude Code CLI version 2.1.259 or newer (or a later build exposing the required safety capabilities). V0.2 is tested on macOS and standard Linux. WSL2 is a supported target but has not yet been independently qualified; native Windows is not supported.

codex plugin marketplace add sanchitmonga22/cc-for-codex --ref main
codex plugin add cc-for-codex@cc-for-codex

Start a new Codex task so the skills are loaded, then say:

Use $claude-setup to check my Claude Code installation.

That setup check is local and makes no model request. Your first useful run can be as simple as:

Use $claude-review to review my current changes.

For a local checkout during development:

codex plugin marketplace add /absolute/path/to/cc-for-codex
codex plugin add cc-for-codex@cc-for-codex

See installation and updates for removal, upgrades, PATH troubleshooting, and direct runner usage.

Required: configure the Codex-first workflow

From this checkout, complete plugin setup with these three lines:

node plugins/cc-for-codex/scripts/install-global-workflow.mjs --check
node plugins/cc-for-codex/scripts/install-global-workflow.mjs --apply
# If legacy role text is reported, review it and rerun --apply --allow-conflicts.

This appends the portable Claude
and Codex blocks to the
absolute global instruction paths. The installer is idempotent, backs up
existing files, and refuses symlink targets. The plugin manager does not run
arbitrary setup scripts during install, so this explicit step is required.

Foreground -p --worktree delegation skips Claude's workspace-trust prompt. Before a background/non--p worktree delegation, open claude interactively in that repository and accept its trust prompt yourself. For dangerous background writes, you must also accept Claude's one-time bypass-responsibility dialog in an interactive non-root Claude session first.

What you get

Skill	Natural-language example	What it does
$claude-code	“Ask Claude for a second opinion on this API.”	Guarded read-only one-shot, persisted handoff, and resume
$claude-review	“Have Claude adversarially review this branch against main.”	Structured standard/adversarial review; opt-in ultrareview
$claude-delegate	“Delegate this fix to Claude in an isolated worktree.”	Foreground/background investigation; dangerous zero-prompt edits by default, with a guarded option
$claude-sessions	“Show my Claude jobs and the latest logs.”	Repo-scoped status, logs, stop, respawn, remove, and attach
$claude-setup	“Check whether Claude Code is ready.”	Binary, version, auth, and feature diagnostics with redaction
$claude-verify	“Verify CC for Codex and run a live smoke test.”	Installed/enabled state, package integrity, local readiness, and optional live proof

Codex-first workflow skills

The plugin also includes a Codex-first workflow for substantial work. Codex remains
the primary planner, implementer, and validator; Claude Code is called only for
an explicitly requested or approved second opinion.

Skill	Use it when	Result
$heavy-track	A change is risky, architectural, multi-file, or multi-session	Routes through concurrent exploration, a challenged plan, one gate, implementation, validation, and two Claude rounds
$heavy-plan	You need the evidence-backed plan before editing	Records the base, alternatives, acceptance criteria, risks, validation, and the first-round Claude challenge
$heavy-build	The plan is approved or autonomous mode is explicitly granted	Implements in scope, proves the result, runs the second-round Claude review, triages findings, and reports verified status

For the full procedure, start with $heavy-track. It does not grant permission
to change global settings, commit, push, merge, publish, or delete worktrees.

Default workflow and model routing

The three workflow skills encode the operating policy below. The model names are
the configured defaults for this workflow, not a promise that every Codex or
Claude host exposes the same IDs. If a default is unavailable, report the
runtime's actual availability and ask before substituting; never claim a model
was used unless the runtime confirms it.

Light track — implement directly, no ceremony

Use this for a bounded change where a plan, fan-out, branch ritual, and gate
would add more overhead than confidence.

Step	Action	Default model
1	Edit in the main Codex session	GPT 5.6 Sol — high
2	Run the project's real validation command	GPT 5.6 Terra — high
3	Paste the real output; no completion claim without it	GPT 5.6 Terra — high
Optional	One Claude Code call only when something feels risky	Opus 5

There is no plan file, fan-out, branch ritual, or approval gate on the light
track. The optional Claude call remains read-only unless a separate write task
is explicitly authorized.

Heavy track — two skills around one stop

$heavy-track dispatches $heavy-plan, stops at one explicit gate, and then
dispatches $heavy-build only after go (or when autonomous mode was
explicitly granted). Resolve BASE first; never assume main. Choose an entry
mode: fresh, resume, or autonomous.

$heavy-plan — no production code is written

1. EXPLORE: fan out all agents in one message, concurrently. Give each
   agent one narrow question. The defaults are Codex gpt-5.6-luna — xhigh for
   architecture, invariants, and failure modes, plus Sonnet 5 Explore/analyzer
   for locations, call sites, and conventions. Five questions means five
   shallow, scoped answers—not one unfocused sweep.
2. PLAN: GPT-6 Astra — high writes ~/.claude/plans/<name>.md with the goal,
   resolved BASE, approach, why alternatives lost, files, validation, risks,
   and out-of-scope boundaries.
3. CHALLENGE: Claude Code attacks the plan—not the implementation—as
   cross-model round 1 of 2. Default: Opus 5 or Fable 5.1.
4. TRIAGE: GPT-6 Astra classifies each point as ACCEPT, INVESTIGATE, or
   REJECT, with evidence. Codex confidence is not evidence.

⛔ Gate — stop. Before go, there is no branch, edit, “prepping files,”
commit, or push. Return the plan path, a concise plan, the triage table,
out-of-scope items, validation commands, and go / change / drop. In
autonomous mode, record that decision in the plan file and continue without
stopping for the chat response.

$heavy-build — only after go

1. BRANCH: create a branch off the resolved BASE before the first edit;
   never commit to BASE. Default: GPT 5.6 Sol — high.
2. IMPLEMENT: stay within the plan and record deviations as they happen.
   Default: GPT 5.6 Sol — high.
3. VALIDATE: run the real command, paste the real output, and rerun until
   green. Default: GPT 5.6 Sol — high.
4. E2E: exercise the running system where the acceptance criteria require
   it; unit tests wearing an E2E costume do not count.
5. REVIEW: Claude Code reviews with --base "$BASE" as cross-model round 2
   of 2. Default: Opus 5 or Fable 5.1, selected by complexity.
6. FIX: triage findings, fix accepted issues, and rerun validation. An
   unverified fix is an unfixed issue. Default: GPT 5.6 Sol — high.
7. REPORT: GPT-6 Astra — high writes
   ~/.claude/plans/<name>-report.md with implemented, validated, E2E-proven,
   reviewed, committed, merged, and deployed status separated.

Human review and merge remain explicit decisions. Neither skill silently
commits, pushes, merges, publishes, or deletes a worktree.

The global workflow installer is reversible. To remove only the managed blocks
later, preview first and then apply explicitly:

node plugins/cc-for-codex/scripts/uninstall-global-workflow.mjs --check
node plugins/cc-for-codex/scripts/uninstall-global-workflow.mjs --apply

The plugin also ships one deterministic, dependency-free Node runner and an optional Stop hook. Familiar aliases match the reverse OpenAI plugin:

OpenAI reverse plugin	CC for Codex	Parity
/codex:setup	setup / $claude-setup	Diagnostic parity; install/login stay explicit
/codex:review	review / $claude-review	Foreground structured review + guarded background mode
/codex:adversarial-review	adversarial-review	Foreground structured review + guarded background mode
/codex:rescue	rescue / $claude-delegate	Fresh/UUID resume; writes use a verified worktree and an explicit permission profile
/codex:status	status / $claude-sessions	Full via Claude agent view JSON
/codex:result	result	Best effort: Claude exposes recent logs, not a result API
/codex:cancel	cancel	Full via recoverable claude stop
/codex:transfer	transfer / handoff	Partial: fresh summarized handoff, not transcript import
Review gate hook	review-gate + bundled Stop hook	Opt-in partial parity: one bounded review, loop guard, and explicit billing consent; reviews the full current dirty tree rather than attributing edits to only the preceding turn

See the complete head-to-head matrix and the recursively audited installed Claude CLI surface.

Safety is part of the interface

The default read-only invocation is not a naked claude -p call. Print mode skips Claude's workspace trust dialog, so the bridge fixes the boundary itself:

--safe-mode --restricted --strict-mcp-config --no-chrome
--permission-mode dontAsk --permission-prompts none
--tools Read,Glob,Grep

• Foreground prompts are sent over stdin to a child process spawned with shell: false.
• The executable launcher resolves Node outside the current repository before loading JavaScript. Claude and Git executables resolved inside the current repository/workspace are also rejected. Guarded Claude children receive only absolute PATH directories that neither live in nor link back into that workspace.
• Project hooks, settings, Claude plugins, MCP servers, Chrome, Bash, network access, edits, and subagents are disabled by default.
• Reviews construct their selected git context locally, require every explicit path to match repository evidence, reject hidden assume-unchanged/skip-worktree entries, disable Claude's file tools, and require a strict non-empty JSON findings schema. Untracked contents, binary bytes, submodules, and truncated diff tails are explicitly reported as partial evidence; source control characters are represented visibly rather than deleted.
• Git calls clear repository-selection environment overrides, disable optional index locks, use a timestamp-preserving temporary index snapshot for diffing, authenticate normal/linked-worktree/submodule .git markers, reject common-directory or alternate-object-store redirection, reject repository-controlled include/includeIf configuration, disable fsmonitor/hooks/textconv, and force submodule recursion off. Before every automatic model launch, the bridge recursively preflights initialized submodules and rejects partial/promisor/shared-object repositories, executable diff configuration, or tracked Git content filters at any level. Write mode also rejects sparse checkouts; ultrareview receives the same Git-startup hardening.
• Write delegation needs explicit permission and a generated worktree-<name> branch based on local HEAD; .claude/worktrees ancestry must be an in-repository real directory, and the returned path, branch, and base commit are independently verified. Claude gets only Read, Glob, Grep, Edit, and Write, never Bash or WebFetch. A failed foreground or background write reports the deterministic/verified recovery location; every background failure preserves a valid printed job ID and stop guidance.
• As requested for this project, write mode defaults to Claude's --dangerously-skip-permissions so delegated file edits do not pause for approvals. The skill automatically includes the separate --confirm-dangerous-permissions bypass-host-safety token after the user has given standing authorization, so it need not ask again within that task. This mode is incompatible with --restricted; Claude can refuse it under managed policy, when run as root/sudo outside a recognized sandbox, or for --bg until its one-time interactive responsibility dialog has been accepted. This is not host isolation: Edit/Write can reach outside the worktree and managed policy hooks may still execute. Use --write-permissions guarded (or CC_FOR_CODEX_WRITE_PERMISSIONS=guarded) for zero-prompt dontAsk + restricted + Edit,Write preapproval.
• Guarded local print-mode ask/review/delegate calls have both a shared outer deadline and bounded --max-turns. Ultrareview has its own minute timeout but no bridge-owned turn cap. Native offers audited finite-command argv/stdin passthrough behind conservative cumulative gates; live stream-JSON protocols and --post are deliberately refused. Background usage and process-visible prompts, ignored-file copying, cloud upload/billing, job removal, state mutation, and native passthrough each have separate confirmation tokens.
• Auth output is allowlisted; email, organization IDs, local project paths, tokens, settings, and environment variables are never printed.
• Ultrareview always forces --no-post. This bridge never posts to GitHub.

Read the threat model and security policy before weakening a guard.

Optional Stop review gate

The bundled hook is installed with the plugin but disabled per repository by default. Enabling it can make one billed Claude review whenever Codex reaches Stop:

Use $claude-setup to show the Stop review gate status.
Use $claude-setup to enable the Stop review gate; I accept billed Claude reviews.
Use $claude-setup to disable the Stop review gate.

From this source checkout, maintainers can invoke the same state operations directly:

RUNNER="plugins/cc-for-codex/scripts/cc-for-codex"

"$RUNNER" review-gate status
"$RUNNER" review-gate enable \
  --confirm-review-gate enable-billed-stop-review
"$RUNNER" review-gate disable

Enablement is stored in the repository's Git common directory, so linked worktrees share it. Installation and enablement do not trust executable hooks: review the current definition and trust its exact hash in Codex /hooks; changed hook definitions require review again. Findings or partial evidence block one continuation, while stop_hook_active prevents a second review in that Stop cycle. Timeout, auth, schema, CLI, or preflight failures fail open with a visible warning; disabled, clean, and loop-guard paths emit no output.

Unlike the official reverse plugin's previous-turn gate, v0.2 cannot reliably attribute dirty files to a single Codex turn from the Stop payload. It reviews the complete current dirty Git tree on each enabled Stop and can therefore block on older or pre-existing changes.

Architecture

flowchart LR
    U[User in Codex] --> S[Focused Codex skill]
    U -->|optional Stop| K[Trusted review hook]
    S --> B[Dependency-free bridge]
    K --> B
    B -->|argv + stdin, no shell| C[Local Claude Code CLI]
    B -->|read-only argv| G[Git diff/status]
    C --> A[Existing Claude authentication]
    C --> J[Claude background supervisor]
    C -. explicit opt-in .-> H[Anthropic cloud / ultrareview]

The plugin is the installable distribution envelope; the skills are the callable workflows. V1 intentionally has no MCP server: claude mcp serve exposes Claude's tools, not Claude as an ask_claude model endpoint, and a local CLI already supplies the needed process boundary. See architecture.

Direct runner examples

Codex normally invokes these through skills. Maintainers can run them directly:

RUNNER="plugins/cc-for-codex/scripts/cc-for-codex"

"$RUNNER" doctor --json
"$RUNNER" ask --prompt "Explain the tradeoff in this design" --persist
"$RUNNER" review --base main --focus "auth and rollback"
"$RUNNER" adversarial-review --path src
"$RUNNER" review --background \
  --confirm-background unbounded-usage \
  --confirm-background-data process-visible-prompt
"$RUNNER" rescue --resume <claude-session-uuid> "continue the investigation"
"$RUNNER" delegate --write \
  --confirm-write isolated-worktree \
  --confirm-dangerous-permissions bypass-host-safety \
  "implement the requested change"
"$RUNNER" status --all

An ultrareview is intentionally noisy to opt into:

"$RUNNER" ultrareview main \
  --confirm-cloud-review upload-and-billing

It uploads review scope to Anthropic's cloud and may consume usage credits. The local installed CLI is authoritative for availability, pricing, and exact timeout behavior.

Official documentation used

OpenAI:

• Build skills
• Build plugins
• Package a plugin
• Hooks
• Connect and test
• Submit a plugin
• Plugin guidelines

Anthropic / Claude Code:

• Complete official documentation index
• CLI reference
• Programmatic/headless mode
• Permission modes
• Sessions
• Background agents and agent view
• Worktrees
• Ultrareview
• MCP
• Claude plugins

The curated official-docs ledger explains the decisions, while the complete Claude documentation coverage snapshot gives every English page in the official index an explicit disposition. npm run audit:docs checks both the page inventory and CLI surface live.

Public distribution status

The GitHub marketplace layout is ready for local, team, and open-source Codex installation. That is different from approval in OpenAI's universal public plugin directory.

OpenAI accepts skills-only plugin submissions, but its current guidelines say it cannot approve plugins that primarily operate as unofficial third-party connectors or pass-through layers. This project also depends on a separately installed local CLI and credentials. Therefore public-directory eligibility is not claimed; it would require Anthropic authorization/brand permission and explicit OpenAI confirmation. See publishing.

Development

npm test
npm run validate
npm run audit:claude
npm run audit:docs
npm run check

The test suite uses a fake claude binary. It makes no Anthropic model request, spends no usage, and tests injection resistance, redaction, exact permission arguments, Git/process isolation, confirmation gates, review structure, and session scoping.

Contributions are welcome. Read CONTRIBUTING.md, SECURITY.md, and the roadmap.

License

MIT