# How Does the Codex Plugin Check for Codex Availability?

> Discover how the Codex plugin checks Codex availability using a two-stage probe: verifying the codex binary and confirming app-server support for a consolidated status.

- Repository: [OpenAI/codex-plugin-cc](https://github.com/openai/codex-plugin-cc)
- Tags: how-to-guide
- Published: 2026-07-08

---

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

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