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

Thrown by runAppServerReview when getCodexAvailability(cwd).available is false. The availability check runs two probes: 'codex --version' (binary present) and 'codex app-server --help' (the app-server subcommand exists). If either fails, Codex cannot host the review thread and the command aborts with install guidance.

Source

Thrown at plugins/codex/scripts/lib/codex.mjs:1005

      transport: client.transport,
      detail: `Interrupted ${turnId} on ${threadId}.`
    };
  } catch (error) {
    return {
      attempted: true,
      interrupted: false,
      transport: client?.transport ?? null,
      detail: error instanceof Error ? error.message : String(error)
    };
  } finally {
    await client?.close().catch(() => {});
  }
}

export async function runAppServerReview(cwd, options = {}) {
  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`.");
  }

  return withAppServer(cwd, async (client) => {
    emitProgress(options.onProgress, "Starting Codex review thread.", "starting");
    const thread = await startThread(client, cwd, {
      model: options.model,
      sandbox: "read-only",
      ephemeral: true,
      threadName: options.threadName
    });
    const sourceThreadId = thread.thread.id;
    emitProgress(options.onProgress, `Thread ready (${sourceThreadId}).`, "starting", {
      threadId: sourceThreadId
    });
    const delivery = options.delivery ?? "inline";

    const turnState = await captureTurn(
      client,

View on GitHub (pinned to db52e28f4d)

Solutions

1. Install or reinstall Codex globally: npm install -g @openai/codex.
2. Rerun /codex:setup so the plugin records the resolved binary path.
3. Confirm 'codex --version' and 'codex app-server --help' both succeed in the same shell/environment before retrying.
4. If using a non-global install, add its bin dir to PATH or point the plugin at the absolute binary path.
5. Upgrade an old build: npm install -g @openai/codex@latest.

Example fix

// before
await runAppServerReview(cwd, { target }) // throws if codex missing

// after (shell setup)
//   npm install -g @openai/codex
//   codex --version && codex app-server --help  # both must succeed
//   /codex:setup
await runAppServerReview(cwd, { target })

import { getCodexAvailability } from './codex.mjs';

async function guardedReview(cwd, options) {
  const avail = getCodexAvailability(cwd);
  if (!avail.available) {
    return { status: 'unavailable', detail: avail.detail };
  }
  return runAppServerReview(cwd, options);
}

null

try {
  await runAppServerReview(cwd, options);
} catch (e) {
  if (/Codex CLI is not installed/.test(e.message)) {
    // prompt user to install, then /codex:setup
  } else throw e;
}

When it happens

Trigger: Invoking runAppServerReview when the 'codex' binary is not on PATH, when 'codex --version' exits non-zero, or when an older Codex build lacks the 'app-server' subcommand (appServerStatus probe fails). getCodexAvailability returns {available:false} in all these cases.

Common situations: Codex CLI was never installed globally. A local/npx install is not on PATH in the current shell. An old pinned Codex version predates the app-server runtime. The codex binary exists but its Node runtime/helper is broken (e.g. missing node_modules after a partial install).

Related errors

• Codex CLI is not installed or is missing required runtime su
• git is not installed. Install Git and retry.
• A Claude session source path is required.
• This Codex version does not support Claude session transfer.
• Codex reported that the Claude import completed, but did not

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