How the Codex Plugin Detects Codex Availability in OpenAI's Codex Plugin CC

The Codex plugin detects availability by executing codex --version to verify the binary exists on PATH, then running codex app-server --help to confirm advanced runtime support, returning a structured status object with detailed failure diagnostics.

The openai/codex-plugin-cc repository implements a robust two-stage detection system to validate the Codex CLI installation before attempting AI-powered code reviews. Understanding how the plugin probes for both binary presence and specific capability flags helps developers troubleshoot environment issues and ensure the advanced app-server runtime is operational.

Two-Stage Detection Architecture

The detection logic follows a sequential validation strategy implemented in plugins/codex/scripts/lib/codex.mjs. This approach ensures that the plugin only attempts to use features actually supported by the installed Codex version, preventing runtime errors during review operations.

Stage 1: Binary Existence Verification

First, the plugin confirms the Codex CLI is installed and accessible. The binaryAvailable helper function, defined in plugins/codex/scripts/lib/process.mjs at lines 38-50, spawns the command codex --version and captures the exit status. If the process returns a non-zero exit code or the binary is not found in PATH, the function immediately returns an object indicating the tool is unavailable with the detail string "not found".

Stage 2: App-Server Capability Check

Once the binary is confirmed, the plugin validates advanced functionality by executing codex app-server --help. This second probe, also invoked through binaryAvailable, verifies that the installed version supports the app-server subcommand required for the plugin's review capabilities. The --help flag safely tests command recognition without executing actual server logic, distinguishing between outdated CLI versions and fully functional installations.

Core Implementation Details

The high-level detection API is exposed through the getCodexAvailability function in plugins/codex/scripts/lib/codex.mjs (lines 886-904). This async function orchestrates the two-stage validation and consolidates the results into a standardized response format containing available (boolean) and detail (string) properties.

When checking the app-server, the function parses stderr and stdout to detect specific error messages such as "unknown option --help", which indicates an older Codex version lacking advanced runtime support. The final detail string concatenates the version number with the runtime status, producing human-readable output like "1.2.3; advanced runtime available".

Practical Integration Example

You can integrate this detection logic into custom tooling by importing the availability checker from the codex module:

import { getCodexAvailability } from "./plugins/codex/scripts/lib/codex.mjs";

async function checkCodex() {
  const cwd = process.cwd();
  const availability = await getCodexAvailability(cwd);

  if (!availability.available) {
    console.error(`Codex not usable: ${availability.detail}`);
    // Prompt installation: npm install -g @openai/codex
  } else {
    console.log(`Codex ready: ${availability.detail}`);
  }
}

checkCodex();

The function returns specific detail strings that indicate the exact failure mode:

• Binary missing: {available: false, detail: "not found"}
• App-server unavailable: {available: false, detail: "1.2.3; advanced runtime unavailable: unknown option --help"}
• Fully operational: {available: true, detail: "1.2.3; advanced runtime available"}

Summary

• The plugin uses process spawning to execute CLI commands rather than checking file paths, ensuring PATH and environment variables are correctly resolved at runtime.
• Two distinct checks are required: first codex --version for binary existence, then codex app-server --help for advanced runtime support.
• The binaryAvailable helper in plugins/codex/scripts/lib/process.mjs handles the low-level command execution and exit code parsing at lines 38-50.
• getCodexAvailability in plugins/codex/scripts/lib/codex.mjs provides the high-level API (lines 886-904) that returns a structured status object with human-readable details.
• The detection system gracefully handles three distinct states: completely missing binary, outdated binary without app-server support, and fully functional installation.

Frequently Asked Questions

What commands does the plugin run to detect Codex availability?

The plugin executes codex --version to verify the binary exists on the system PATH. If successful, it then runs codex app-server --help to confirm the advanced runtime subcommand is supported. These commands are spawned asynchronously through the binaryAvailable helper function, which captures exit codes and stderr content to determine availability.

Where is the detection logic implemented in the codebase?

The high-level detection API lives in plugins/codex/scripts/lib/codex.mjs within the getCodexAvailability function (lines 886-904). The underlying process execution logic is implemented in plugins/codex/scripts/lib/process.mjs in the binaryAvailable function (lines 38-50), which handles the actual subprocess spawning and error handling.

What does the availability status object contain?

The detection functions return an object with two properties: available (a boolean indicating whether Codex can be used) and detail (a descriptive string). The detail field contains version numbers on success or specific error messages like "not found" when the binary is missing, or "unknown option" when the app-server subcommand is unavailable in older Codex versions.

How does the plugin handle missing Codex installations?

When the binary is not found or the app-server command fails, the getCodexAvailability function returns {available: false, ...} with a descriptive detail string explaining the specific failure. This allows calling code to detect exactly which component is missing and prompt the user to install or upgrade the Codex CLI via npm install -g @openai/codex before attempting further operations.

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