openai/codex-plugin-cc · error · Error

Codex CLI is not installed or is missing required runtime su

Error message

Codex CLI is not installed or is missing required runtime support. Install it with `npm install -g @openai/codex`, then rerun `/codex:setup`.

What it means

ensureCodexAvailable calls getCodexAvailability(cwd) which probes for the `codex` binary and required runtime support. If unavailable, every task/review command aborts here because they all need to spawn or connect to `codex app-server`. The message directs the user to install globally and rerun setup.

Source

Thrown at plugins/codex/scripts/codex-companion.mjs:255

  const finalReport = await buildSetupReport(cwd, actionsTaken);
  outputResult(options.json ? finalReport : renderSetupReport(finalReport), options.json);
}

function buildAdversarialReviewPrompt(context, focusText) {
  const template = loadPromptTemplate(ROOT_DIR, "adversarial-review");
  return interpolateTemplate(template, {
    REVIEW_KIND: "Adversarial Review",
    TARGET_LABEL: context.target.label,
    USER_FOCUS: focusText || "No extra focus provided.",
    REVIEW_COLLECTION_GUIDANCE: context.collectionGuidance,
    REVIEW_INPUT: context.content
  });
}

function ensureCodexAvailable(cwd) {
  const availability = getCodexAvailability(cwd);
  if (!availability.available) {
    throw new Error("Codex CLI is not installed or is missing required runtime support. Install it with `npm install -g @openai/codex`, then rerun `/codex:setup`.");
  }
}

function buildNativeReviewTarget(target) {
  if (target.mode === "working-tree") {
    return { type: "uncommittedChanges" };
  }

  if (target.mode === "branch") {
    return { type: "baseBranch", branch: target.baseRef };
  }

  return null;
}

function validateNativeReviewRequest(target, focusText) {
  if (focusText.trim()) {
    throw new Error(

View on GitHub (pinned to db52e28f4d)

Solutions

1. Run: npm install -g @openai/codex
2. Verify `codex --version` works in the SAME shell/env the companion runs in (check PATH includes npm global bin).
3. Rerun /codex:setup to confirm getCodexAvailability now reports available.
4. If installed but unavailable, check node version and native dependencies required by codex.

Example fix

// before (codex missing)
codex-companion.mjs task "do work"
// after
npm install -g @openai/codex && codex-companion.mjs task "do work"

const avail = getCodexAvailability(cwd);
if (!avail.available) {
  throw new Error('codex unavailable: ' + JSON.stringify(avail));
}

/** @returns {boolean} */
function isCodexReady(cwd) { return getCodexAvailability(cwd).available; }

When it happens

Trigger: First run on a machine without @openai/codex installed, after a global uninstall, when codex is installed but the PATH in the agent's env does not include the npm global bin, or when the codex binary exists but fails its runtime support probe (e.g. incompatible node/native deps).

Common situations: Fresh CI environment, container without codex baked in, or a node version mismatch where codex launches but its native module check fails.

Related errors

• Codex CLI is not installed or is missing required runtime su
• git is not installed. Install Git and retry.
• Choose either --enable-review-gate or --disable-review-gate.
• A Claude session source path is required.
• This Codex version does not support Claude session transfer.

AI-assisted analysis of openai/codex-plugin-cc@db52e28f4d (2026-08-13). Data as JSON: /api/errors/421c4b0052e35c46. Report an issue: GitHub.