# How to Troubleshoot Common Issues with the Codex Plugin

> Troubleshoot common Codex plugin issues. Fix missing binaries, authentication problems, and misconfigured broker modes to get your plugin running smoothly. Learn solutions now.

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

---

**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 <email>"
- **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`:

```javascript
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

```bash

# 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

```bash

# 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

```javascript
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.