How to Troubleshoot Common Issues with the Codex Plugin

Most Codex plugin failures stem from three root causes: a missing or outdated codex binary, authentication issues with OpenAI or ChatGPT credentials, and misconfigured shared-runtime broker modes.

The Codex plugin for Claude Code is a thin wrapper around the Codex CLI and its app-server runtime. Understanding how the plugin handles authentication checks, turn capture, and broker connections makes diagnosing issues straightforward. This guide covers the specific failure points, diagnostic commands, and recovery steps found in the openai/codex-plugin-cc repository.

Core Architecture

The plugin operates through three primary layers that commonly fail independently:

• Slash commands (/codex:review, /codex:rescue, etc.) expose functionality to Claude Code. These are defined in plugins/codex/commands/*.md.

• CodexAppServerClient is a thin JSON-RPC client that communicates with the local Codex binary. The implementation lives in plugins/codex/scripts/lib/app-server.mjs.

• Turn-capture logic collects progress, errors, and results from running Codex turns. Key functions include captureTurn, applyTurnNotification, and recordItem in plugins/codex/scripts/lib/codex.mjs.

Additional utilities handle authentication (getCodexAuthStatus, getCodexAuthStatusFromClient) and binary availability (getCodexAvailability), while broker logic in withAppServer and withDirectAppServer manages shared-runtime modes.

Typical Failure Points

Binary Availability and Version Mismatch

The plugin aborts immediately if the codex binary is missing or outdated. The function getCodexAvailability in codex.mjs validates the installation by running codex --version and codex app-server --help. If either check fails, the plugin returns a clear "Codex not installed" error before attempting any operations.

Authentication Failures

getCodexAuthStatus queries the app-server via account/read and config/read RPC calls to determine login state. The function returns structured status indicating:

• ChatGPT login: "ChatGPT login active for "
• API key present: "API key configured (unverified)" or verified status
• No credentials: Explicit "not authenticated" state

If the CLI reports authentication issues, the plugin cannot proceed with review or rescue operations.

Shared-Runtime Broker Misconfiguration

When running in shared mode (activated via BROKER_ENDPOINT_ENV), the plugin attempts to connect to a persistent broker process. If the endpoint is unreachable (ENOENT or ECONNREFUSED), the client falls back to direct mode through the withAppServer helper. However, if the broker is partially alive but busy, you may encounter "Broker busy" errors that require manual intervention.

Turn-Level Errors and Stalls

Codex emits errors as error notifications during turn execution. The plugin converts these into progress messages via emitProgress(state.onProgress, \Codex error: …`, "failed"). Additionally, stderr from the underlying process is captured through cleanCodexStderr` and reported back to the user.

If a turn hangs indefinitely, the interruptAppServerTurn function (lines 01060-01099 in codex.mjs) sends a turn/interrupt RPC to the app-server. If the turn never responds to the interrupt, the capture logic falls back to an inferred completion after a timeout.

Troubleshooting Checklist

Symptom	Likely Cause	Diagnostic Command	Resolution
"Codex not installed" error	Binary missing or outdated	Run /codex:setup or check getCodexAvailability output	Install or upgrade: npm install -g @openai/codex
"not authenticated" message	Missing login or invalid API key	Run /codex:setup or call getCodexAuthStatus programmatically	Execute !codex login or verify ~/.codex/config.toml credentials
"Broker busy" / "connection refused"	Shared broker endpoint unavailable	Check BROKER_ENDPOINT_ENV or run codex broker status	Restart broker: codex broker stop && codex broker start, or unset the env var to force direct mode
Turn stalls with no final answer	Turn capture timed out	Inspect progress output and stderr field	Use /codex:cancel <task-id> to abort, then re-run with --background
Missing review text after /codex:review	Review thread failed or sandbox restriction	Check reviewText field and stderr for "permission denied"	Ensure repository is accessible and adjust sandbox with --sandbox=read-write if needed
externalAgentConfig/import/completed never arrives	Outdated Codex CLI lacking session import	Run /codex:transfer and watch for "Importing Claude session"	Upgrade Codex: npm install -g @openai/codex@latest

Quick Diagnostic Script

Run this Node.js script to mirror the internal checks used by /codex:setup:

import { getCodexAvailability, getCodexAuthStatus } from
  "https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/scripts/lib/codex.mjs";

async function diagnose(cwd) {
  console.log("🔍 Checking binary …");
  console.log(await getCodexAvailability(cwd));

  console.log("\n🔐 Checking auth …");
  console.log(await getCodexAuthStatus(cwd));
}

diagnose(process.cwd()).catch(console.error);

This script imports the same helper functions the plugin uses, providing identical output to the built-in diagnostics.

Practical Recovery Examples

Running a Review and Inspecting Results

# Start a review in the background

/codex:review --background

# Check execution status

/codex:status

# Retrieve the final result object

/codex:result

Internally, this invokes runAppServerReview (lines 01002-01055 in codex.mjs), which verifies binary availability, starts a temporary thread, calls client.request("review/start", …), and captures the turn via captureTurn. The returned JSON contains reviewText, reasoningSummary, and stderr for debugging.

Cancelling a Stuck Task

# Cancel using the task ID shown by /codex:status

/codex:cancel task-abc123

This triggers interruptAppServerTurn, sending a "turn/interrupt" RPC to the app-server and returning a concise status object indicating whether the interruption succeeded.

Checking Broker Mode Programmatically

import { getSessionRuntimeStatus } from
  "https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/scripts/lib/codex.mjs";

console.log(await getSessionRuntimeStatus(process.env, process.cwd()));

The function inspects BROKER_ENDPOINT_ENV and any persisted broker session (see loadBrokerSession in broker-lifecycle.mjs) to report whether you are running in shared or direct mode.

Summary

• Verify binary availability first using getCodexAvailability or /codex:setup before troubleshooting deeper issues.
• Check authentication status with getCodexAuthStatus to confirm OpenAI or ChatGPT login state.
• Inspect stderr fields in turn results to identify Codex-specific errors not captured in the main output.
• Manage broker mode by checking BROKER_ENDPOINT_ENV and using getSessionRuntimeStatus when encountering connection refusals.
• Cancel stalled operations using /codex:cancel or the interruptAppServerTurn API to prevent indefinite hangs.

Frequently Asked Questions

Why does the plugin say "Codex not installed" when I have the CLI?

The plugin requires both the base codex command and the app-server helper. getCodexAvailability specifically checks codex app-server --help in addition to codex --version. If the app-server subcommand is missing, you are likely running a version prior to the introduction of the app-server architecture. Upgrade to the latest global package: npm install -g @openai/codex@latest.

How do I switch from shared broker mode to direct mode?

Unset the BROKER_ENDPOINT_ENV environment variable or ensure it is not defined in your shell profile. The plugin's withAppServer logic automatically falls back to direct mode (spawning a new process per turn) when this variable is absent. Alternatively, restart the broker with codex broker stop && codex broker start to clear stale connections.

What does "API key configured (unverified)" mean in the auth status?

This status from getCodexAuthStatus indicates that a credentials file exists at ~/.codex/config.toml containing an API key, but the Codex CLI has not yet validated it against OpenAI's servers. Run codex login to trigger verification, or proceed with commands—the CLI will verify the key on first use and update the status accordingly.

Where are the turn errors and stderr captured when a review fails?

Turn-level errors appear as error notifications processed by applyTurnNotification in codex.mjs. The plugin surfaces these through the stderr field of the result object returned by runAppServerReview. When running /codex:review, inspect the JSON output's stderr property for permission denied messages, sandbox violations, or Codex-specific stack traces.

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