How the Codex Plugin Checks for Codex Availability and Guides Installation

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.

// 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, 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:

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.

// 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 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.

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