How Does the Codex Plugin Check for Codex Availability?

The Codex plugin performs a two-stage probe by first verifying the codex binary exists via codex --version, then confirming advanced runtime support through codex app-server --help, returning a consolidated status object with availability details.

The openai/codex-plugin-cc repository provides integration tools for the Codex CLI, including robust detection logic to determine whether the Codex environment is properly configured. Understanding how the Codex plugin checks for Codex availability helps developers troubleshoot installation issues and ensures the advanced app-server features are accessible before executing review or task commands.

The Two-Stage Availability Detection Process

The detection strategy implemented in plugins/codex/scripts/lib/codex.mjs follows a sequential validation approach that first locates the binary, then verifies specific capabilities.

Stage 1: Binary Existence Verification

The plugin initiates the check by calling binaryAvailable("codex", ["--version"], ...) from the helper module plugins/codex/scripts/lib/process.mjs. This spawns the codex --version command to confirm the CLI is present on the system PATH and executable. If this command fails or returns a non-zero exit code, the function immediately returns {available: false, detail: "not found"}.

Stage 2: App-Server Capability Check

Once the binary is confirmed, the plugin proceeds to validate advanced runtime support. It executes binaryAvailable("codex", ["app-server", "--help"], ...) to verify that the app-server subcommand is implemented in the installed version. This step ensures backward compatibility with older Codex CLI versions that may lack the advanced runtime features required by the plugin.

Implementation Details in process.mjs and codex.mjs

The low-level execution logic resides in plugins/codex/scripts/lib/process.mjs, where the binaryAvailable function (lines 38-50) handles process spawning, exit code capture, and timeout management. It returns a standardized object containing:

• available: Boolean indicating success
• detail: Descriptive string for logging or error reporting

The high-level orchestration occurs in plugins/codex/scripts/lib/codex.mjs within the getCodexAvailability function (lines 886-904). This async function accepts a cwd parameter for execution context, chains the two validation calls, and constructs a consolidated result object that includes version information when available.

Practical Usage Example

Here is how to implement the availability check in your own scripts:

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

async function checkCodex() {
  const cwd = process.cwd();               // or any directory you want to test in
  const availability = getCodexAvailability(cwd);

  if (!availability.available) {
    console.error(`Codex not usable: ${availability.detail}`);
    // Prompt the user to install/update Codex, e.g. `npm install -g @openai/codex`
  } else {
    console.log(`Codex is ready: ${availability.detail}`);
    // Proceed with review or task commands
  }
}

checkCodex();

The function returns specific detail strings depending on the failure mode:

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

Summary

• The Codex availability check uses process spawning to validate the CLI environment before executing commands.
• The binaryAvailable helper in process.mjs handles the actual command execution and exit code analysis.
• Two distinct checks are required: first for binary existence (codex --version), then for app-server support (codex app-server --help).
• The getCodexAvailability function in codex.mjs consolidates these checks into a single API with detailed status reporting.
• Results include specific detail strings that identify whether the binary is missing or if the installed version lacks advanced runtime capabilities.

Frequently Asked Questions

What happens if the Codex CLI is not installed?

If the codex binary is not found on the system PATH, the binaryAvailable helper returns {available: false, detail: "not found"}, allowing the plugin to prompt users to install the CLI via npm install -g @openai/codex before attempting further operations.

How does the plugin distinguish between different failure modes?

The getCodexAvailability function interprets distinct exit codes and stderr outputs from the spawned processes. A missing binary produces a "not found" detail, while a binary that lacks the app-server subcommand returns a version-prefixed error message indicating the advanced runtime is unavailable.

Why does the plugin check for app-server separately from the binary?

The app-server component represents the advanced runtime features that may not exist in older Codex CLI versions. By running codex app-server --help as a secondary check, the plugin ensures it only attempts to use capabilities that are actually implemented, preventing runtime errors during review or task execution.

Can I use the availability check in custom Node.js automation scripts?

Yes, the getCodexAvailability function is exported from plugins/codex/scripts/lib/codex.mjs and can be imported into any Node.js project. You must provide a working directory (cwd) parameter, and the function will return a promise resolving to the availability status object you can use to gate Codex-dependent functionality.

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