DOCSEARCHbyAlgolia
Submit Docs

Codex Plugin for Claude Code

repository·main·Indexed 12 days ago

https://github.com/openai/codex-plugin-cc

A plugin for Claude Code that integrates Codex's code review and task delegation capabilities. It provides commands for standard and adversarial code reviews (/codex:review, /codex:adversarial-review), task delegation via a subagent (/codex:rescue), and session transfers to the Codex App or TUI (/codex:transfer). Version 1.0.6 requires Node.js 18.18 or later and an OpenAI API key or ChatGPT subscription.

Tokens
12.5K
Snippets
41
Records
51
Agent score
98%

What's inside Codex

  1. How the codex-cli-runtime skill works

    main

    The codex-cli-runtime is an internal helper skill designed to be used exclusively within the codex:codex-rescue subagent. It acts as a pure forwarder to the Codex companion runtime via a Node.js script.

    Core Mental Model:

    • Forwarder, not Orchestrator: The subagent's sole responsibility is to invoke the task command once and return the resulting stdout unchanged.
    • No Independent Analysis: The subagent must not inspect the repository, read files, grep, or perform any analysis. Its only allowed work is optionally using the gpt-5-4-prompting skill to rewrite the user's request into a tighter prompt before the single task call.
    • Single Invocation: Only one task invocation is permitted per rescue handoff.
    node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-companion.mjs" task "<raw arguments>"

  2. How to compose prompts for GPT-5.4 tasks in Codex

    main

    When using the codex:codex-rescue workflow, you should prompt Codex as an operator rather than a collaborator. Prompts should be compact, block-structured using XML tags, and avoid long natural-language explanations in favor of explicit prompt contracts.

    Core Prompting Rules

    • One task per run: Split unrelated requests into separate Codex runs.
    • Define 'Done': Explicitly state the desired end state; do not assume Codex will infer it.
    • Use XML tags: Maintain a stable internal structure using consistent XML tags.
    • Prioritize contracts: Use better prompt contracts (output shapes, verification rules) instead of increasing reasoning complexity or adding prose.
    • Grounding: Add explicit grounding and verification rules for tasks where unsupported guesses would degrade quality.

  3. Default prompt recipe and XML block structure

    main

    Construct prompts using the following XML block structure to ensure stable execution and clear output contracts:

    Standard Blocks

    • <task>: The concrete job and relevant repository or failure context.
    • <structured_output_contract> or <compact_output_contract>: Exact shape, ordering, and brevity requirements.
    • <default_follow_through_policy>: Instructions on 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 tasks prone to drift.

    Task-Specific Blocks

    • Coding/Debugging: Add completeness_contract, verification_loop, and missing_context_gating.
    • Review/Adversarial Review: Add grounding_rules, structured_output_contract, and dig_deeper_nudge.
    • Research/Recommendation: Add research_mode and citation_rules.
    • Write-capable tasks: Add action_safety to prevent unrelated refactors.

  4. Prompt assembly checklist

    main

    Before sending a prompt to Codex, verify it against this checklist:

    1. Define Scope: Is the exact task and scope defined in <task>?
    2. Minimize Output: Is the output contract the smallest possible shape that remains easy to use?
    3. Set Policy: Has a decision been made on whether Codex should continue by default or stop for missing high-risk details?
    4. Apply Safety/Verification: Are verification, grounding, and safety tags included only where necessary?
    5. Prune Redundancy: Have all redundant instructions been removed?

  5. Run the Codex setup command

    main

    The setup command checks if the local Codex CLI is ready for use and can optionally toggle the stop-time review gate. If Codex is not installed and npm is available, the system will prompt you to install it. If you choose to install, it will execute npm install -g @openai/codex and then re-run the setup to verify the installation.

    If Codex is installed but you are not authenticated, you will be prompted to run !codex login to complete the setup.

    node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-companion.mjs" setup --json $ARGUMENTS

  6. Use /codex:review to run a code review

    main

    The /codex:review command runs a Codex code review against your local git state using the shared built-in reviewer. This command is strictly for reviewing; it will not fix issues, apply patches, or suggest changes. It returns the Codex output verbatim.

    Arguments

    [--wait|--background] [--base <ref>] [--scope auto|working-tree|branch]

    • --wait: Runs the review in the foreground. The process will wait for the review to complete before returning results.
    • --background: Runs the review as a Claude background task.
    • --base <ref>: Specifies a git reference (like a branch name or commit hash) to use as the base for the review.
    • --scope <scope>: Defines the scope of the review. Supported values are:
      • auto: Automatic detection of changes.
      • working-tree: Reviews changes in the working tree.
      • branch: Reviews changes relative to a branch.

    Execution Modes

    If you do not provide --wait or --background, the plugin will estimate the size of the review (based on git status and git diff) and ask you which mode you prefer:

    1. Wait for results (Recommended for tiny reviews, ~1-2 files).
    2. Run in background (Recommended for most other cases).

    If you need custom review instructions or more adversarial framing, use /codex:adversarial-review instead.

    /codex:review --base main --scope branch

  8. Install the Codex plugin for Claude Code

    main

    To use Codex within your Claude Code workflow, follow these steps to add the marketplace, install the plugin, and initialize the setup:

    1. Add the marketplace:
      /plugin marketplace add openai/codex-plugin-cc
    2. Install the plugin:
      /plugin install codex@openai-codex
    3. Reload plugins:
      /reload-plugins
    4. Run setup:
      /codex:setup

    Requirements:

    • Node.js 18.18 or later.
    • A ChatGPT subscription (including Free) or an OpenAI API key.

    Manual Installation (if needed): If /codex:setup cannot install Codex for you, install it globally via npm:

    npm install -g @openai/codex

    If you are not logged in, run !codex login within Claude Code.

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

  9. Use Codex Prompt Recipes for task construction

    main

    Codex Prompt Recipes are XML-based templates designed for constructing high-fidelity prompts for Codex or GPT-5.4 tasks.

    Usage Guidelines:

    • Selection: Copy the smallest recipe that fits your specific task and trim any unnecessary sections.
    • Execution in codex:codex-rescue: When using these recipes within the codex:codex-rescue command, diagnosis and fix-oriented recipes will run in write mode by default, unless you explicitly request read-only behavior.

    These recipes are categorized by intent: Diagnosis, Narrow Fix, Root-Cause Review, Research/Recommendation, and Prompt-Patching.

  10. Guidelines for presenting Codex helper output

    main

    When displaying output from a Codex helper, follow these structural and behavioral rules to ensure accuracy and safety:

    Data Integrity

    • Structure: Preserve the helper's verdict, summary, findings, and next steps structure.
    • Ordering: For review output, present findings first and order them by severity.
    • Precision: Use file paths and line numbers exactly as reported. Preserve evidence boundaries (e.g., distinctions between inferences, uncertainties, or follow-up questions).
    • Sections: Maintain all requested output sections, such as observed facts, inferences, open questions, touched files, or next steps.
    • Errors: If the helper reports malformed output or a failed run, include the most actionable stderr lines and stop. Do not attempt to guess the intent.
    • Empty States: If there are no findings, state this explicitly and keep the residual-risk note brief.
    • Edits: If Codex made edits, state this explicitly and list the touched files provided by the helper.

    Safety and Constraints

    • Review Findings (CRITICAL): After presenting review findings, you MUST STOP. Do not make code changes or fix issues automatically. You must explicitly ask the user which issues they want fixed before touching any files. Auto-applying fixes is strictly forbidden.
    • Rescue Operations (codex:rescue):
      • If a Codex run fails or is incomplete, report the failure and stop. Do not attempt a Claude-side implementation.
      • If Codex was never successfully invoked, do not generate a substitute answer.
    • Authentication: If the helper reports that setup or authentication is required, direct the user to /codex:setup. Do not attempt to improvise alternate authentication flows.

  11. Use /codex:adversarial-review to challenge implementation design

    main

    The /codex:adversarial-review command runs a Codex review specifically designed to challenge implementation approaches, design choices, tradeoffs, and assumptions. Unlike a standard review that looks for defects, this is a 'challenge review' focused on whether the current approach is correct and where it might fail under real-world conditions.

    Core Behavior:

    • It is review-only. It will not fix issues, apply patches, or suggest changes.
    • It returns Codex's output verbatim.
    • It supports selecting review targets via scope or base references.

    Argument Syntax: [--wait|--background] [--base <ref>] [--scope auto|working-tree|branch] [focus ...]

    Supported Scopes:

    • auto: Automatically determines the scope.
    • working-tree: Reviews the current working tree (including untracked files).
    • branch: Reviews the current branch.
    • --base <ref>: Used for base-branch reviews (e.g., comparing against a specific git ref).

    Note: This command does not support --scope staged or --scope unstaged.

    /codex:adversarial-review --scope working-tree "Review the new authentication logic for potential race conditions"

  12. Choose the correct Codex command for your task

    main

    Select the appropriate command based on the nature of your task:

    • review or adversarial-review: Use these built-in commands when the job is specifically reviewing local git changes. These commands automatically include the necessary review contracts.
    • task: Use this for diagnosis, planning, research, or implementation when you need direct control over the prompt structure.
    • task --resume-last: Use this for follow-up instructions on an existing Codex thread. When using this, send only the delta instruction (the change) rather than restating the entire prompt, unless the direction has changed materially.