Skip to content
/

Codex Plugin for Claude Code (openai)

codex-plugin-cc · openai/codex-plugin-cc · ★ 20k · last commit 2026-04-18

Use OpenAI Codex as a reviewer and task executor from inside an active Claude Code session without leaving the CC workflow.

Best whenClaude orchestrates; Codex executes — the subagent must be a thin forwarder that returns Codex stdout verbatim and does nothing else.
Skip ifSubagent inspecting the repository independently, Claude paraphrasing or summarizing Codex output
vs seeds
superpowersis a pure skills-only behavioral framework that never leaves the Claude …
Primitive shape 14 total
Commands 7 Skills 3 Subagents 1 Hooks 3
00

Summary

codex-plugin-cc — Summary

Elevator pitch: The official OpenAI-authored Claude Code plugin that lets Claude Code users invoke OpenAI Codex as a reviewer and task executor from inside an active Claude Code session. It ships six slash-commands (/codex:review, /codex:adversarial-review, /codex:rescue, /codex:status, /codex:result, /codex:cancel) plus a codex:codex-rescue subagent that forwards heavyweight coding tasks to Codex via a companion Node.js script (codex-companion.mjs). Codex plays the reviewer role by default and the worker role when rescue mode is activated; Claude Code remains the orchestrator throughout. The plugin installs from the Claude Code marketplace in three shell commands and requires only a ChatGPT subscription or OpenAI API key alongside the existing Claude subscription. It is the canonical first-party reference for the CC-Codex bridging idiom: Claude orchestrates → Codex executes/reviews → results surface back in the CC session. Compared to seeds: differs from superpowers (which is skills-only with zero external agents) by delegating real execution to a second-party model; differs from claude-flow (which owns its own runtime) by being a thin companion wrapper; most closely resembles ccmemory in using an external MCP/companion process, but the peer model is another AI agent rather than a database.

01

Overview

codex-plugin-cc — Overview

Origin

Published by OpenAI under the openai GitHub organization (Apache-2.0). Released alongside the Claude Code plugin marketplace announcement. It is explicitly described as a bridge for "Claude Code users who want an easy way to start using Codex from the workflow they already have." Last commit: 2026-04-18. 19,674 stars, 1,183 forks — by far the most starred plugin in this batch.

Philosophy

The plugin is philosophically minimalist: it does not try to redesign Claude Code's workflow. Instead it inserts Codex as a peer agent for the two scenarios where Codex adds distinct value over Claude — adversarial code review and rapid model-routing rescue. The README states:

"Use Codex from inside Claude Code to review code or delegate tasks to Codex."

The design decision to keep Claude as the orchestrator (not Codex) is an intentional sovereignty choice. Commands like /codex:review are explicitly read-only and must not apply patches. The codex-rescue subagent is described as a "thin forwarding wrapper" — it is not permitted to inspect the repo, add independent analysis, or do follow-up work. All real reasoning happens inside the Codex subprocess.

Key Architectural Claim

The codex-companion.mjs script is the single-seam abstraction: all six commands and the rescue subagent funnel through it. This makes the Claude ↔ Codex boundary explicit and testable.

Manifesto Quotes (verbatim)

  • "One simple first run is: /codex:review --background / /codex:status / /codex:result"
  • "Leave --effort unset unless the user explicitly requests a specific reasoning effort."
  • "The subagent is a thin forwarder only. It should use one Bash call to invoke node ... codex-companion.mjs task ... and return that command's stdout as-is."
  • "Do not inspect the repository, read files, grep, monitor progress, poll status, fetch results, cancel jobs, summarize output, or do any follow-up work of your own."
02

Architecture

codex-plugin-cc — Architecture

Distribution

  • Type: Claude Code plugin (marketplace-installable)
  • Marketplace slug: openai/codex-plugin-cc
  • Plugin name: codex@openai-codex
  • Language: JavaScript / Node.js (TypeScript source, compiled)
  • License: Apache-2.0

Install

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

Then optionally: npm install -g @openai/codex and codex login.

Required Runtime

  • Node.js 18.18+
  • @openai/codex CLI (npm global install)
  • ChatGPT subscription (Free+) or OpenAI API key
  • Active Claude Code session

Directory Tree (inside plugin)

plugins/codex/
├── .claude-plugin/          # marketplace metadata
├── commands/
│   ├── adversarial-review.md
│   ├── cancel.md
│   ├── rescue.md
│   ├── result.md
│   ├── review.md
│   ├── setup.md
│   └── status.md
├── skills/
│   ├── codex-cli-runtime/   # internal skill: SKILL.md
│   ├── codex-result-handling/ # internal skill: SKILL.md
│   └── gpt-5-4-prompting/   # internal skill: SKILL.md
├── agents/
│   └── codex-rescue.md      # subagent definition
├── hooks/
│   └── hooks.json           # SessionStart, SessionEnd, Stop
├── prompts/
│   ├── adversarial-review.md
│   └── stop-review-gate.md
└── scripts/
    └── codex-companion.mjs  # runtime bridge script

Target AI Tools

  • Primary: Claude Code (as host / orchestrator)
  • Peer: OpenAI Codex CLI (as reviewer / worker)

Key Design Pattern

The codex-companion.mjs script acts as the seam between Claude Code and the Codex CLI. All slash-commands are thin wrappers that call node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-companion.mjs" <subcommand> <args> via a single Bash invocation.

03

Components

codex-plugin-cc — Components

Commands (7)

Name Purpose
codex:review Read-only Codex review of uncommitted changes or branch diff
codex:adversarial-review Steerable challenge review — questions design choices, tradeoffs, hidden assumptions
codex:rescue Delegates investigation/fix/continuation to the codex:codex-rescue subagent
codex:status Lists running and recent Codex background jobs for the current repo
codex:result Shows stored Codex output for a finished job
codex:cancel Cancels an active background Codex job
codex:setup Verifies Codex is installed, authenticated, and hooks are wired

All commands have disable-model-invocation: true except rescue, and all are restricted in allowed-tools.

Skills (3, internal / non-user-invocable)

Name Purpose
codex-cli-runtime Internal contract for the rescue subagent: how to call codex-companion.mjs task
codex-result-handling Internal guidance for surfacing Codex job results
gpt-5-4-prompting Guidance for composing tight XML-structured prompts for Codex / GPT-5.4 tasks

Subagents (1)

Name Definition format Purpose
codex:codex-rescue persona-md (agents/codex-rescue.md) Thin forwarder: invokes codex-companion.mjs task via one Bash call, returns stdout verbatim

The rescue subagent is a Sonnet-model agent with tools: Bash only, granted access to codex-cli-runtime and gpt-5-4-prompting skills.

Hooks (3 events)

Event Script Purpose
SessionStart session-lifecycle-hook.mjs Initialize session state for background job tracking
SessionEnd session-lifecycle-hook.mjs SessionEnd Cleanup session-scoped job tracking
Stop stop-review-gate-hook.mjs Optional stop-time gate that can block completion pending review

Scripts (1 primary)

Name Purpose
scripts/codex-companion.mjs Node.js runtime bridge: wraps Codex CLI subcommands (review, adversarial-review, task, status, result, cancel, task-resume-candidate, background-routing-context)

Prompts (2)

  • prompts/adversarial-review.md — system prompt for adversarial review framing
  • prompts/stop-review-gate.md — prompt for the optional stop-gate gate
05

Prompts

codex-plugin-cc — Prompts

Prompt 1: codex:codex-rescue subagent definition (verbatim excerpt)

Source: plugins/codex/agents/codex-rescue.md

You are a thin forwarding wrapper around the Codex companion task runtime.

Your only job is to forward the user's rescue request to the Codex companion script. Do not do anything else.

Forwarding rules:

- Use exactly one `Bash` call to invoke `node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-companion.mjs" task ...`.
- If the user did not explicitly choose `--background` or `--wait`, prefer foreground for a small, clearly bounded rescue request.
- If the user did not explicitly choose `--background` or `--wait` and the task looks complicated, open-ended, multi-step, or likely to keep Codex running for a long time, prefer background execution.
- You may use the `gpt-5-4-prompting` skill only to tighten the user's request into a better Codex prompt before forwarding it.
- Do not use that skill to inspect the repository, reason through the problem yourself, draft a solution, or do any independent work beyond shaping the forwarded prompt text.
- Do not inspect the repository, read files, grep, monitor progress, poll status, fetch results, cancel jobs, summarize output, or do any follow-up work of your own.

Prompting technique: Hard-constraint enumeration with explicit prohibition lists. The prompt defines what the subagent IS NOT allowed to do (inspect, grep, summarize) more specifically than what it is allowed to do. This "negative space definition" is unusual and effective for preventing scope creep in forwarder subagents.


Prompt 2: codex-cli-runtime internal skill (verbatim excerpt)

Source: plugins/codex/skills/codex-cli-runtime/SKILL.md

Use this skill only inside the `codex:codex-rescue` subagent.

Primary helper:
- `node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-companion.mjs" task "<raw arguments>"`

Execution rules:
- The rescue subagent is a forwarder, not an orchestrator. Its only job is to invoke `task` once and return that stdout unchanged.
- Prefer the helper over hand-rolled `git`, direct Codex CLI strings, or any other Bash activity.
- Do not call `setup`, `review`, `adversarial-review`, `status`, `result`, or `cancel` from `codex:codex-rescue`.
- Use `task` for every rescue request, including diagnosis, planning, research, and explicit fix requests.
- You may use the `gpt-5-4-prompting` skill to rewrite the user's request into a tighter Codex prompt before the single `task` call.
- That prompt drafting is the only Claude-side work allowed.

Prompting technique: Operational constraint injection via internal skill. By separating the "how to call Codex" knowledge from the agent's persona, the plugin allows the runtime contract to be versioned independently.


Prompt 3: gpt-5-4-prompting skill (verbatim excerpt)

Source: plugins/codex/skills/gpt-5-4-prompting/SKILL.md

Default prompt recipe:
- `<task>`: the concrete job and the relevant repository or failure context.
- `<structured_output_contract>` or `<compact_output_contract>`: exact shape, ordering, and brevity requirements.
- `<default_follow_through_policy>`: what Codex should do by default instead of asking routine questions.
- `<verification_loop>` or `<completeness_contract>`: required for debugging, implementation, or risky fixes.
- `<grounding_rules>` or `<citation_rules>`: required for review, research, or anything that could drift into unsupported claims.

Prompting technique: XML-tagged block-structured prompt engineering guide. Encodes OpenAI's recommended prompt structure for Codex (GPT-5.4 family) as a reusable meta-skill. This is the only skill in the batch that teaches prompt engineering for a peer AI model rather than instructing an AI on domain tasks.

09

Uniqueness

codex-plugin-cc — Uniqueness

differs_from_seeds

The closest seed is superpowers — both are Claude Code plugins distributed via a plugin marketplace. However, superpowers is a pure skills-only behavioral framework that never leaves the Claude Code sandbox, whereas codex-plugin-cc is fundamentally an inter-AI bridge: it exits the Claude Code process space and invokes a second AI agent (OpenAI Codex) as a peer. The architectural delta is that superpowers changes how Claude thinks; codex-plugin-cc changes who executes the task. Compared to claude-flow, which bundles 305 MCP tools and owns its own runtime, codex-plugin-cc is deliberately minimal (6 commands, 1 subagent, 1 companion script) and delegates everything substantive to the Codex subprocess. The "thin forwarder" design philosophy is the sharpest contrast with claude-flow's "everything in the runtime" approach.

Positioning

First-party, authoritative reference implementation for the Claude Code ↔ OpenAI Codex bridging idiom. Its design choices (read-only review commands, write-capable rescue subagent, background job tracking, stop-gate hook) are likely to be canonical for the pattern.

Observable Failure Modes

  1. Codex auth failure: If OPENAI_API_KEY is missing or expired, all commands fail silently at the companion script level. /codex:setup detects this but the other commands have no fallback.
  2. Background job loss: Job tracking is session-scoped; closing the Claude Code session loses in-progress job references (Codex continues running but Claude loses the job ID).
  3. Rescue scope creep: Despite the "thin forwarder" constraint, the gpt-5-4-prompting skill can rewrite prompts — a misconfigured prompt rewrite could change the task meaning before it reaches Codex.
  4. Stop gate timeout: The Stop hook has a 900-second timeout. A blocked gate can leave the session in a zombie state.
  5. Context sanitization gap: Unlike ching-kuo/claude-codex which explicitly blocks .env files, codex-plugin-cc has no documented secret-scrubbing before forwarding task text to Codex.

Most Unusual Feature

The gpt-5-4-prompting internal skill — a meta-skill that teaches Claude how to write better prompts for a different AI model. It encodes OpenAI's recommended XML-block prompt recipe (task, structured_output_contract, default_follow_through_policy, verification_loop, grounding_rules) as reusable Claude knowledge. No other framework in this batch contains a skill about prompt engineering for a peer AI.

04

Workflow

codex-plugin-cc — Workflow

Phases + Artifacts

Phase Trigger Artifact
1. Setup /codex:setup Codex installed, auth verified, hooks wired
2a. Review /codex:review [--background] [--base <ref>] Codex review output (stdout verbatim)
2b. Adversarial Review /codex:adversarial-review [focus text] Challenge review output emphasizing tradeoffs and design questions
2c. Rescue /codex:rescue <task> Codex implementation/investigation output via codex:codex-rescue subagent
3. Monitor /codex:status [job-id] List of active/recent jobs with status
4. Retrieve /codex:result [job-id] Final stored Codex output + Codex session ID for codex resume
5. Cancel /codex:cancel [job-id] Cancels active background job

Approval Gates (2)

Gate Type Trigger
Background vs. foreground selection choice-list (AskUserQuestion) When neither --wait nor --background is passed; estimated from git diff --shortstat
Resume vs. new thread choice-list (AskUserQuestion) In /codex:rescue when a prior Codex thread exists and neither --resume nor --fresh is passed

Stop Gate (Optional)

The Stop hook runs stop-review-gate-hook.mjs (900s timeout). When enabled (via /codex:setup), it can block the session from completing until the review gate passes.

Execution Mode

Supports both foreground (wait) and background (background task with job tracking). Background jobs use Claude Code's Bash(..., run_in_background: true) and the codex:codex-rescue subagent's background path.

Codex Role in This Workflow

  • Reviewer: default role in /codex:review and /codex:adversarial-review — read-only, returns structured critique
  • Worker: activated via /codex:rescue — can write files, investigate bugs, continue prior sessions
06

Memory Context

codex-plugin-cc — Memory and Context

State Storage

  • Job tracking: Session-scoped background job IDs and status are managed by session-lifecycle-hook.mjs (SessionStart/SessionEnd). Jobs are stored in memory for the session duration and retrievable via /codex:status and /codex:result.
  • Codex session IDs: The Codex CLI generates session IDs for each run. /codex:result surfaces the Codex session ID, allowing the user to codex resume <session-id> to reopen the Codex context.
  • Resume threads: codex-companion.mjs task-resume-candidate --json checks for resumable Codex threads in the current repo, enabling the --resume / --fresh routing gate.

Persistence

  • Session-scoped only: Job tracking is session-scoped (managed by hooks). No persistent DB or file-based state.
  • Codex-side persistence: Codex CLI maintains its own session state internally; the plugin surfaces the session ID but does not own the persistence.

Compaction

  • No explicit compaction handling. The codex-result-handling internal skill provides guidance on how to surface large outputs, but truncation/compaction is Codex CLI's responsibility.

Cross-Session Handoff

  • Enabled via Codex session IDs. A user can exit Claude Code and later codex resume <session-id> to continue where Codex left off.
  • Within Claude Code: --resume flag on /codex:rescue allows continuing the latest Codex rescue thread in the repo.

Memory Type

None (session-only job tracking). The plugin does not write persistent memory files to the project.

07

Orchestration

codex-plugin-cc — Orchestration

Multi-Agent Pattern

Hierarchical (Claude CC as orchestrator → Codex as worker/reviewer).

  • Claude Code session is always the parent.
  • Codex runs as a child process via codex-companion.mjs.
  • The codex:codex-rescue subagent is dispatched via the Claude Code Agent tool with subagent_type: "codex:codex-rescue" — a named typed subagent, not a generic Task spawn.

Isolation Mechanism

  • Process isolation: Codex runs as a separate OS process, invoked via node codex-companion.mjs task.
  • Context isolation: The rescue subagent has tools: Bash only and user-invocable: false skills — it cannot call Review, Status, Result, or any non-forwarding tool.

Multi-Model

Yes — this is the canonical multi-model bridge in this batch:

Role Model
Orchestrator / planning Claude (Sonnet or Opus, CC user's active model)
Reviewer / worker OpenAI Codex (GPT-5.3-codex, GPT-5.4, GPT-5.4-mini, or user-selected)

The --model flag on /codex:rescue allows selecting the Codex model: gpt-5.3-codex-spark (mapped from alias spark), gpt-5.4-mini, etc. The rescue subagent leaves model unset by default (Codex picks its own default).

Execution Mode

  • Foreground: command waits for Codex output (suitable for small reviews)
  • Background: command dispatches and returns immediately; job tracked via session-lifecycle-hook.mjs; user polls with /codex:status and /codex:result

Consensus Mechanism

None. Single-Codex outputs; no multi-reviewer consensus.

Prompt Chaining

Yes — gpt-5-4-prompting skill can rewrite the user's prompt before forwarding to Codex. This constitutes a single-stage prompt chain (Claude rewrites prompt → Codex executes rewritten prompt).

Parallel Execution

Not supported for reviews (one Codex job at a time per command invocation). Multiple background jobs can exist for different commands in the same session.

08

Ui Cli Surface

codex-plugin-cc — UI and CLI Surface

Dedicated CLI Binary

None. The plugin is installed and operated entirely through Claude Code's /plugin and slash-command system. No standalone binary is provided.

Local UI

None. All user interaction is through the Claude Code conversation interface.

Slash Commands as UI

The 7 slash-commands (/codex:review, /codex:adversarial-review, /codex:rescue, /codex:status, /codex:result, /codex:cancel, /codex:setup) are the full user-facing surface. Each command has:

  • argument-hint for IDE tab-completion
  • disable-model-invocation: true on review/status/result/cancel commands (pure script execution)
  • Restricted allowed-tools lists preventing unintended tool use

IDE Integration

Designed exclusively for Claude Code. No Cursor, Gemini CLI, or Kiro integration.

Observability

  • Job status: /codex:status [job-id] — lists active and recent background jobs
  • Job results: /codex:result [job-id] — shows stored output + Codex session ID
  • Stop gate: Optional Stop hook can surface a review gate before the Claude session ends
  • Session lifecycle hooks: SessionStart/SessionEnd hooks track job lifecycle, with 5-second timeouts

Cross-Tool Portability

Low / single-tool. The plugin architecture is specific to Claude Code's plugin system; Codex is the only supported peer model.

Related frameworks

same archetype · same primary tool · same memory type

Claude-Flow / Ruflo ★ 55k

Eliminates single-agent context limits and sequential bottlenecks by orchestrating fault-tolerant swarms of specialized AI agents…

Hermes Agent (NousResearch) ★ 168k

Self-improving personal AI agent with closed learning loop, 7 terminal backends, and messaging gateway — not tied to any AI…

OpenCode ★ 165k

Terminal-first AI coding agent with multi-model routing, native desktop app, and a typed .opencode/ configuration system for…

OpenHands ★ 75k

Open-source AI software development platform (open-source Devin alternative) with Docker sandbox isolation, 77.6% SWE-bench…

DeerFlow ★ 70k

Long-horizon superagent that researches, codes, and creates by orchestrating parallel sub-agents with isolated contexts in Docker…

oh-my-openagent (omo) ★ 60k

Multi-provider AI agent orchestration for OpenCode: escape vendor lock-in by routing Sisyphus (Claude/Kimi/GLM) and Hephaestus…