# How the Codex Plugin Checks for Codex Availability and Guides Installation

> Learn how the Codex plugin checks for Codex availability using CLI commands and guides users through installation with npm install -g @openai/codex.

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

---

**The Codex plugin verifies CLI availability by executing `codex --version` and `codex app-server --help` through the `getCodexAvailability` function, and if the binary is missing, it prompts users to run `npm install -g @openai/codex` via the interactive setup command.**

The openai/codex-plugin-cc repository provides a robust mechanism for detecting whether the Codex CLI is installed and functional on a user's system. When the CLI is missing or the advanced runtime is unavailable, the plugin guides users through an automated installation process using npm. Understanding how the **Codex availability check** works helps developers troubleshoot deployment issues and ensures the advanced runtime features are properly configured.

## Detecting Codex Availability Through Binary Checks

The plugin determines whether the Codex CLI is ready to run by performing two lightweight checks implemented in `plugins/codex/scripts/lib/codex.mjs` (lines 886-900). These checks verify both basic binary presence and advanced runtime capabilities.

### Verifying Binary Presence with `codex --version`

The first check runs `codex --version` to confirm the executable exists on the system. This command is executed through the **`binaryAvailable`** helper function defined in `plugins/codex/scripts/lib/process.mjs` (lines 38-50). If the command returns a non-zero exit code or triggers an `ENOENT` error, the function returns `available: false` with a descriptive detail message.

### Validating Advanced Runtime with `codex app-server --help`

The second check runs `codex app-server --help` to verify that the Codex "app-server" sub-command is functional. This is required for the advanced runtime features. According to the source code in `plugins/codex/scripts/lib/codex.mjs`, if the app-server check fails, the function returns a combined error message indicating both the version status and the specific advanced runtime failure.

## The `binaryAvailable` Helper Function

The **`binaryAvailable`** function in `plugins/codex/scripts/lib/process.mjs` executes subprocess commands and interprets the results. It accepts a command name, version arguments, and options, then returns a standardized availability object.

```javascript
// plugins/codex/scripts/lib/process.mjs
export function binaryAvailable(command, versionArgs = ["--version"], options = {}) {
  const result = runCommand(command, versionArgs, options);
  if (result.error && result.error.code === "ENOENT") {
    return { available: false, detail: "not found" };
  }
  if (result.error) {
    return { available: false, detail: result.error.message };
  }
  if (result.status !== 0) {
    const detail = result.stderr.trim() || result.stdout.trim() || `exit ${result.status}`;
    return { available: false, detail };
  }
  return { available: true, detail: result.stdout.trim() || result.stderr.trim() || "ok" };
}

```

This helper distinguishes between "command not found" errors (`ENOENT`) and other execution failures, providing clear diagnostics for the availability check.

## Guiding Installation via the Setup Command

When a user invokes the **`setup`** command defined in [`plugins/codex/commands/setup.md`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/commands/setup.md), the plugin initiates an interactive installation workflow if Codex is unavailable.

### The Interactive Installation Prompt

The setup process calls `getCodexAvailability` to determine the current state. If Codex is unavailable and the Node package manager (`npm`) is present, the plugin uses the **`AskUserQuestion`** tool to present two options:

- **Install Codex (Recommended)**
- **Skip for now**

Selecting the install option triggers the following command:

```bash
npm install -g @openai/codex

```

After installation completes, the plugin automatically re-executes the setup command to verify the new installation. If Codex is already installed but not authenticated, the setup output preserves guidance to run `codex login`.

## Implementation of `getCodexAvailability`

The **`getCodexAvailability`** function orchestrates both availability checks and constructs detailed status messages. Located in `plugins/codex/scripts/lib/codex.mjs`, it sequentially validates the binary and app-server functionality.

```javascript
// plugins/codex/scripts/lib/codex.mjs
export function getCodexAvailability(cwd) {
  const versionStatus = binaryAvailable("codex", ["--version"], { cwd });
  if (!versionStatus.available) {
    return versionStatus;               // codex binary not found
  }

  const appServerStatus = binaryAvailable("codex", ["app-server", "--help"], { cwd });
  if (!appServerStatus.available) {
    return {
      available: false,
      detail: `${versionStatus.detail}; advanced runtime unavailable: ${appServerStatus.detail}`
    };
  }

  return {
    available: true,
    detail: `${versionStatus.detail}; advanced runtime available`
  };
}

```

This function accepts a `cwd` (current working directory) parameter and returns an object containing both the availability boolean and a human-readable detail string explaining the specific state of the installation.

## Summary

- The **Codex availability check** relies on two subprocess commands: `codex --version` for basic binary presence and `codex app-server --help` for advanced runtime verification.
- The **`getCodexAvailability`** function in `plugins/codex/scripts/lib/codex.mjs` (lines 886-900) encapsulates these checks and returns structured status objects.
- The **`binaryAvailable`** helper in `plugins/codex/scripts/lib/process.mjs` (lines 38-50) handles command execution and distinguishes between missing binaries and execution errors.
- The **setup command** in [`plugins/codex/commands/setup.md`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/commands/setup.md) provides interactive installation guidance using the `AskUserQuestion` tool when `npm` is available but Codex is missing.
- Successful installation triggers `npm install -g @openai/codex`, followed by automatic re-verification of the setup.

## Frequently Asked Questions

### What happens if Codex is installed but not authenticated?

If the **Codex CLI** is detected as available but lacks authentication, the setup command preserves guidance to run `codex login`. The availability check only verifies binary presence and app-server functionality, not API credentials. Users must authenticate separately after installation.

### Can the plugin install Codex without npm?

No, the automated installation flow requires **npm** to be available on the system. The `setup` command specifically checks for npm availability before prompting the user to install Codex. If npm is missing, the plugin cannot automatically install the Codex CLI and will instruct the user to install Node.js and npm first.

### What is the advanced runtime check for?

The **`codex app-server --help`** check verifies that the Codex CLI includes the "app-server" sub-command required for advanced runtime features. According to the source code in `plugins/codex/scripts/lib/codex.mjs`, this ensures the installed version supports the full functionality expected by the plugin, not just basic command-line availability.

### How does the plugin handle command execution errors?

The **`binaryAvailable`** function handles three specific error cases: `ENOENT` (command not found), general execution errors, and non-zero exit codes. It returns standardized objects with `available: false` and descriptive detail messages. This allows `getCodexAvailability` to provide specific feedback about whether the binary is missing or merely non-functional.