# How to Debug Codex Plugin Integration Issues: A Complete Troubleshooting Guide

> Troubleshoot Codex plugin integration problems. Learn to debug binary checks authentication turn capture and broker configurations effectively. Get your integration working now.

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

---

**Debug Codex plugin integration failures by verifying binary availability with `getCodexAvailability`, checking authentication via `getCodexAuthStatus`, inspecting turn capture output in `captureTurn`, and validating broker configuration through `BROKER_ENDPOINT_ENV` or direct mode fallback.**

The Codex plugin for Claude Code, maintained in the `openai/codex-plugin-cc` repository, functions as a thin wrapper around the Codex CLI and its app-server runtime. When you need to debug Codex plugin integration issues, you are tracing failures across three pillars: binary availability, authentication state, and runtime mode configuration.

## Architecture Components Critical for Debugging

Understanding the plugin's internal architecture helps you identify exactly where failures occur. The integration relies on several key components defined in the source code.

### The CodexAppServerClient RPC Layer

At the heart of the plugin lies the **`CodexAppServerClient`**, implemented in `plugins/codex/scripts/lib/app-server.mjs`. This thin JSON-RPC client communicates with the local Codex binary's app-server runtime. When commands fail, this client either returns structured errors or falls back from broker mode to direct mode via the `withAppServer` helper function.

### Turn Capture and Error Propagation

The **`captureTurn`** function in `plugins/codex/scripts/lib/codex.mjs` (along with `applyTurnNotification` and `recordItem`) collects progress, errors, and results from running Codex turns. Errors emitted by Codex appear as `error` notifications and convert to progress messages via `emitProgress`, while the underlying process `stderr` is sanitized through `cleanCodexStderr` and reported back to the user.

### Authentication and Availability Verification

Before executing commands, the plugin validates the environment through **`getCodexAvailability`** (which checks `codex --version` and `codex app-server --help`) and **`getCodexAuthStatus`** (which queries the app-server via `account/read` and `config/read` RPC calls). These functions return structured status objects indicating whether the user is logged in via ChatGPT or using an unverified API key.

## Common Failure Points and Diagnostic Steps

Most integration issues cluster around five specific failure modes. Use the following diagnostic approach to isolate and resolve each.

### Binary Not Installed or Outdated

When the `codex` binary is missing or outdated, `getCodexAvailability` returns a failure status and the plugin aborts with a clear message.

**Diagnostic command:**

Run `/codex:setup` or programmatically call `getCodexAvailability(cwd)` from `plugins/codex/scripts/lib/codex.mjs`.

**Fix:**

Install or upgrade the CLI:

```bash
npm install -g @openai/codex

```

### Authentication Problems

The **`getCodexAuthStatus`** function queries the app-server to determine if the user has an active ChatGPT login ("ChatGPT login active for <email>") or an unverified API key ("API key configured (unverified)").

**Diagnostic command:**

Execute `/codex:setup` or call `getCodexAuthStatus(cwd)` programmatically.

**Fix:**

Log in via `!codex login` and ensure `~/.codex/config.toml` contains valid credentials.

### Shared Runtime Broker Misconfiguration

The plugin supports a **shared runtime mode** using the `BROKER_ENDPOINT_ENV` environment variable. If the broker endpoint is unreachable (`ENOENT` or `ECONNREFUSED`), the client retries with a direct connection through `withAppServer` and `withDirectAppServer`.

**Diagnostic:**

Check `BROKER_ENDPOINT_ENV` or run `codex broker status`.

**Fix:**

Restart the broker:

```bash
codex broker stop
codex broker start

```

Alternatively, unset the environment variable to force direct mode.

### Turn-Level Errors

During execution, errors surface through the turn capture system. The **`stderr`** field in result objects contains sanitized error output from the Codex process.

**Diagnostic:**

Inspect the `stderr` field returned by `runAppServerReview` or `runAppServerTurn` functions (lines 01002-01055 in `codex.mjs`).

### Interrupted or Stalled Turns

When a turn hangs, the **`interruptAppServerTurn`** function (lines 01060-01099) sends a `turn/interrupt` RPC to cancel the operation. If capture times out, the logic infers completion after a short delay.

**Diagnostic:**

Use `/codex:status` to identify task IDs, then apply `/codex:cancel <task-id>`.

## Quick Diagnostic Script

You can run the same checks the plugin uses internally with this Node.js script:

```javascript
import { getCodexAvailability, getCodexAuthStatus } from "./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 imports the exact helper functions from `plugins/codex/scripts/lib/codex.mjs`, ensuring the output mirrors what `/codex:setup` displays.

## Debugging Specific Workflows

### Review Command Failures

When `/codex:review` produces missing output, the **`runAppServerReview`** function has likely encountered sandbox restrictions or import errors.

**Debug steps:**

1. Run with background flag: `/codex:review --background`
2. Check status: `/codex:status`
3. Retrieve results: `/codex:result`

Inspect the `reviewText` and `stderr` fields in the returned JSON. If you see "permission denied" messages, adjust sandbox permissions using `--sandbox=read-write` instead of the default read-only mode.

### Cancelling Stuck Tasks

For hung operations, identify the task ID from `/codex:status` output, then execute:

```bash
/codex:cancel task-abc123

```

This triggers `interruptAppServerTurn`, which sends the `turn/interrupt` RPC and returns a concise status object.

### Session Import Issues

The `/codex:transfer` command relies on `importExternalAgentSession` (lines 01058-01093). If `externalAgentConfig/import/completed` never arrives, you are likely using an older Codex version lacking session-import support.

**Fix:**

Upgrade the Codex CLI:

```bash
npm install -g @openai/codex@latest

```

### Verifying Runtime Mode

To determine whether you are using shared or direct mode, inspect the runtime status:

```javascript
import { getSessionRuntimeStatus } from "./plugins/codex/scripts/lib/codex.mjs";

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

```

This function, defined in the codex module, checks `BROKER_ENDPOINT_ENV` and any persisted broker session via `loadBrokerSession` in `plugins/codex/scripts/lib/broker-lifecycle.mjs`.

## Summary

- **Verify binary availability** using `getCodexAvailability` before troubleshooting deeper issues.
- **Check authentication** via `getCodexAuthStatus` to ensure valid ChatGPT login or API key configuration.
- **Inspect turn output** by examining the `stderr` field and `captureTurn` results for specific error messages.
- **Manage broker mode** by checking `BROKER_ENDPOINT_ENV` and using direct mode fallback if the shared runtime fails.
- **Cancel stalled operations** with `interruptAppServerTurn` or the `/codex:cancel` command to prevent indefinite hangs.

## Frequently Asked Questions

### How do I check if the Codex plugin can find the binary?

Run the `getCodexAvailability` function from `plugins/codex/scripts/lib/codex.mjs` or execute `/codex:setup` in Claude Code. This verifies that `codex --version` returns a valid version and that the `codex app-server --help` command is recognized. If either check fails, install the CLI globally with `npm install -g @openai/codex`.

### What causes the "Broker busy" or "connection refused" errors?

These errors indicate that the `BROKER_ENDPOINT_ENV` environment variable points to a shared runtime that is unreachable or not running. The plugin attempts to retry with a direct connection via `withAppServer`, but you can resolve the issue by restarting the broker with `codex broker stop` followed by `codex broker start`, or by unsetting the environment variable to force direct mode.

### Why does my Codex review return empty results?

Empty reviews typically occur when the turn capture times out or the Codex process encounters sandbox restrictions. Inspect the `reviewText` and `stderr` fields in the result object returned by `runAppServerReview`. If the `stderr` contains permission errors, rerun the command with `--sandbox=read-write` to grant necessary file system access.

### Where does the plugin store authentication status?

The plugin queries the Codex CLI configuration in real-time through `getCodexAuthStatus`, which calls `account/read` and `config/read` RPC methods on the app-server. It does not cache credentials; it reads from `~/.codex/config.toml` and the active CLI session. If you see "API key configured (unverified)" or authentication errors, verify your login status with `codex login` or by checking the config file directly.