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

> Learn how the Codex plugin detects Codex availability. It checks for the binary and confirms runtime support for detailed diagnostics.

- Repository: [OpenAI/codex-plugin-cc](https://github.com/openai/codex-plugin-cc)
- Tags: internals
- Published: 2026-07-04

---

**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:

```javascript
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.