Prerequisites for Using the Codex Plugin: Complete Setup Guide

To use the Codex plugin for Claude Code, you need a valid OpenAI credential (ChatGPT subscription or API key), Node.js 18.18 or higher, and the Codex CLI installed on your system.

The openai/codex-plugin-cc repository provides a thin wrapper that integrates OpenAI's Codex CLI into Claude Code. Before executing slash commands like /codex:review, you must satisfy three core dependencies that bridge the gap between the Claude environment and OpenAI's code generation services.

Core Prerequisites

Valid OpenAI Credentials

The plugin forwards all usage to your Codex limits, requiring either a ChatGPT subscription (including the free tier) or an OpenAI API key. According to the repository's README.md, these credentials authenticate requests to the Codex app-server. The plugin does not manage billing or quota; it simply passes through your existing OpenAI authentication state.

Node.js 18.18 or Higher

The plugin is built with modern JavaScript/TypeScript and specifically requires Node.js version 18.18 or greater. This requirement is declared in the project's package.json and enforced because the plugin relies on Node.js features introduced in that version. Attempting to run the plugin on older Node.js versions will result in compatibility errors.

Codex CLI Binary

Unlike self-contained plugins, this integration calls the external codex binary from your environment. The plugin does not ship its own runtime; instead, it loads the global codex command and reuses your existing configuration files (~/.codex/config.toml or .codex/config.toml in the repo). If the binary is missing, the /codex:setup command will detect this and offer to install it automatically.

Architecture Overview

Understanding the data flow clarifies why these prerequisites are mandatory:

Claude Code → Codex plugin → Codex CLI → Codex app-server

When you invoke /codex:review, the plugin constructs a command in plugins/codex/scripts/lib/codex.mjs and forwards the request to the local Codex app-server. Because the plugin acts as a passthrough layer, it depends entirely on the external CLI for actual code analysis.

Installation and Verification

Follow these steps to satisfy all prerequisites:

# Install the plugin (requires Node ≥ 18.18)

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

# Verify setup and auto-install CLI if missing

/codex:setup

If you prefer manual installation or the auto-install fails:

# Install Codex CLI globally

npm install -g @openai/codex

# Authenticate (required if using API key only)

!codex login

Running /codex:setup after these steps validates that all components are present and properly configured.

Key Integration Files

The following files enforce the prerequisite checks:

• README.md – Documents the Node.js version requirements and credential setup.
• plugins/codex/scripts/lib/codex.mjs – The wrapper script that locates and executes the local codex binary.
• package.json – Declares the minimum Node.js runtime version.
• .claude-plugin/plugin.json – Registers the plugin with Claude Code's extension system.

Summary

• OpenAI credential required – Either a ChatGPT subscription or API key to access Codex limits.
• Node.js 18.18+ mandatory – The plugin uses modern JavaScript features unavailable in earlier versions.
• External CLI dependency – The codex binary must be installed separately; the plugin wraps rather than embeds the runtime.
• Auto-installation available – Running /codex:setup can automatically fetch the CLI if missing.
• Configuration reuse – The plugin reads from ~/.codex/config.toml and local .codex/config.toml files.

Frequently Asked Questions

Do I need a paid OpenAI subscription to use the Codex plugin?

No. According to the openai/codex-plugin-cc source code, you can use either a ChatGPT subscription (including the free tier) or an OpenAI API key. The plugin forwards usage to your existing Codex limits, so billing depends on your OpenAI account type.

Can I run the Codex plugin without installing the Codex CLI separately?

No. The plugin requires the external codex binary to be present in your environment. However, if you run /codex:setup and the binary is missing, the plugin will offer to install it automatically. Alternatively, you can manually install it via npm install -g @openai/codex.

What happens if my Node.js version is older than 18.18?

The plugin will fail to load or execute. The package.json in the repository explicitly declares Node.js 18.18 as the minimum requirement, and the code uses features incompatible with earlier versions. You must upgrade Node.js before installing the plugin.

Where does the Codex plugin store its configuration?

The plugin reuses the standard Codex CLI configuration files. It reads from ~/.codex/config.toml for global settings and .codex/config.toml within your repository for project-specific overrides. This allows the plugin to maintain authentication state and preferences across sessions.

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