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

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:

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 ") 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:

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:

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:

/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:

npm install -g @openai/codex@latest

Verifying Runtime Mode

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

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.

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