What Functionalities Does the Codex Plugin Offer? Core Commands and Architecture Explained

The Codex plugin for Claude Code provides eight slash commands that enable read-only code reviews, adversarial analysis, task delegation, session transfer, and background job management by wrapping the local Codex CLI in a thin client-side adapter.

The openai/codex-plugin-cc repository delivers a client-side integration layer that connects Claude Code directly to the local Codex binary. This plugin transforms Claude Code into a control center for OpenAI's Codex CLI, allowing developers to invoke AI-powered code analysis and automated task execution without leaving their editor or relying on external services.

Core Slash Commands

The plugin exposes a comprehensive command set through markdown definitions stored in plugins/codex/commands/. Each command maps to a specific sub-command implemented in the central dispatcher script.

Read-Only Code Review

The /codex:review command executes a read-only analysis of your repository. According to the source code in plugins/codex/commands/review.md, this command can evaluate uncommitted changes, branch diffs, or custom scopes. The implementation delegates to scripts/codex-companion.mjs, which invokes the review sub-command and respects the user's existing Codex configuration in ~/.codex/config.toml or project-level .codex/config.toml.

Adversarial Review

For steerable analysis, /codex:adversarial-review accepts extra focus text that challenges design decisions and identifies risk areas. Defined in plugins/codex/commands/adversarial-review.md, this command triggers the adversarial-review branch of codex-companion.mjs, allowing you to supply custom prompts such as "look for race conditions and question the chosen approach."

Task Delegation and Rescue

The /codex:rescue command hands concrete tasks to Codex via the codex-rescue sub-agent. As specified in plugins/codex/commands/rescue.md, this supports bug investigation, fixing failing tests, and code generation. The heavy lifting occurs in the task mode of codex-companion.mjs, which can run in background mode while you continue working.

Session Transfer

/codex:transfer exports the current Claude Code session as a Codex-compatible thread. The implementation in plugins/codex/commands/transfer.md calls the transfer sub-command, which uses lib/claude-session-transfer.mjs to locate the Claude transcript file and invoke Codex's importExternalAgentSession function. This generates a session ID you can resume with codex resume <session-id>.

Job Management

The plugin provides three commands for managing background operations:

• /codex:status – Displays the state of all background Codex jobs (running, completed, or failed) by reading from the job store in lib/state.mjs.
• /codex:result – Retrieves final output from finished jobs, including the session ID needed to reopen discussions in the Codex app.
• /codex:cancel – Terminates running background jobs by interacting with the process management layer in lib/job-control.mjs.

Setup and Configuration

The /codex:setup command verifies that the Codex binary is installed and that the user is authenticated. This command, defined in plugins/codex/commands/setup.md, uses the buildSetupReport helper in codex-companion.mjs to generate a status report.

Review Gate

When enabled via /codex:setup --enable-review-gate, this functionality forces a targeted Codex review after every Claude turn. The stop-hook defined in plugins/codex/scripts/stop-review-gate-hook.mjs consults the plugin's state (state.mjs) and blocks Claude's continuation if the review finds issues, requiring user acknowledgment before proceeding.

Architecture and Implementation

The plugin's architecture follows a clean separation between command definitions, dispatch logic, and state management.

Command Discovery and Dispatch

Each slash command is described in a Markdown file under plugins/codex/commands/. The Claude Code runtime parses these files to expose commands to the user. All commands delegate to scripts/codex-companion.mjs, a Node.js entry point that parses arguments via lib/args.mjs, resolves the workspace through lib/workspace.mjs, and routes to the appropriate operation handler.

Job Management and State

Background tasks are tracked via a lightweight JSON-based job store implemented in lib/state.mjs and lib/job-control.mjs. Each job receives a UUID, with progress logs written to state/ files. The status and result commands read from this persistent store, enabling you to check on long-running reviews or rescue operations hours after initiating them.

Codex CLI Integration

The companion script invokes the local Codex CLI through functions like binaryAvailable, runAppServerReview, and runAppServerTurn. Because the plugin executes the same binary available in your $PATH, it automatically respects your existing Codex configuration and authentication state without requiring additional API keys or external service credentials.

Session Transfer Mechanics

Session export functionality relies on lib/claude-session-transfer.mjs to locate the Claude transcript file, then calls Codex's external-agent importer. This creates a persistent Codex thread that maintains conversation context, allowing seamless handoff from Claude Code's iterative editing environment to Codex's specialized UI for extended discussions.

How to Use the Codex Plugin

After installing the plugin (/plugin install codex@openai-codex) and ensuring the Codex CLI is available (npm install -g @openai/codex), you can invoke these commands directly in Claude Code:

# Run a foreground review of uncommitted changes

/codex:review

# Run a review in the background (recommended for large changes)

/codex:review --background

# Review a specific branch comparison

/codex:review --base main

# Execute an adversarial review with custom focus

/codex:adversarial-review --background look for race conditions and question the chosen approach

# Delegate a bug fix to Codex

/codex:rescue --background fix the failing test with the smallest safe patch

# Resume a previous rescue job

/codex:rescue --resume

# Transfer current session to Codex

/codex:transfer

# Check background job status

/codex:status
/codex:status <job-id>

# Retrieve finished job results

/codex:result
/codex:result <job-id>

# Cancel a running job

/codex:cancel <job-id>

# Verify installation and enable review gate

/codex:setup --enable-review-gate

Summary

• The Codex plugin provides eight slash commands (review, adversarial-review, rescue, transfer, status, result, cancel, setup) that bridge Claude Code and the local Codex CLI.
• Command definitions live in plugins/codex/commands/*.md and dispatch through scripts/codex-companion.mjs.
• Background job management uses lib/state.mjs and lib/job-control.mjs to track UUID-based tasks with persistent logging.
• Session transfer allows exporting Claude conversations to Codex via lib/claude-session-transfer.mjs and the importExternalAgentSession function.
• The review gate optionally enforces Codex reviews before Claude can proceed, implemented via stop-review-gate-hook.mjs.

Frequently Asked Questions

What do I need to install before using the Codex plugin?

You must install the Codex CLI globally (npm install -g @openai/codex) and verify it is in your system PATH. The /codex:setup command checks for the binary and authentication status, reporting any missing dependencies before you attempt to run reviews or tasks.

How does the review gate functionality work?

When enabled via /codex:setup --enable-review-gate, the plugin installs a stop-hook that triggers after every Claude turn. The hook invokes stop-review-gate-hook.mjs, which runs a targeted Codex review and checks the output against schemas/review-output.schema.json. If the review identifies issues, Claude blocks further execution until you acknowledge the findings, effectively forcing a code review checkpoint in your workflow.

Can I run multiple Codex reviews simultaneously?

Yes. By appending the --background flag to /codex:review or /codex:rescue, you delegate the operation to a background process managed by lib/job-control.mjs. Use /codex:status to monitor all active jobs and /codex:result to retrieve outputs when they complete, allowing you to queue multiple analyses while continuing to edit code.

How do I continue a conversation in Codex after starting it in Claude Code?

Use /codex:transfer to export your current Claude session. This command invokes codex-companion.mjs with the transfer sub-command, which uses lib/claude-session-transfer.mjs to package your transcript and call Codex's importExternalAgentSession. The command outputs a session ID that you can use with codex resume <session-id> to continue the discussion in the native Codex application.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}