How the Codex Plugin Interacts with the OpenAI API: A Technical Deep Dive

The Codex plugin does not call the OpenAI API directly; instead, it invokes the local codex binary to start an app-server, then sends RPC calls like review/start and turn/start that the server forwards to OpenAI endpoints using authentication stored by the Codex CLI.

The openai/codex-plugin-cc repository serves as a bridge between Claude Code and OpenAI's Codex CLI. Rather than implementing direct HTTP requests to OpenAI's REST endpoints, the plugin relies on a local Codex app-server to handle all networking, authentication, and provider resolution. This architecture isolates the plugin from API complexities while enabling support for multiple model providers including OpenAI, Ollama, and LM Studio.

The Indirect Communication Architecture

The plugin's interaction with the OpenAI API is entirely mediated through the locally installed Codex CLI. When you run a slash command like /codex:review in Claude Code, the plugin spawns the codex binary (installed via npm install -g @openai/codex), which starts a lightweight HTTP-JSON server implementing the OpenAI API surface. This app-server listens on a Unix socket or TCP port and exposes RPC endpoints that the plugin consumes.

The flow decouples the plugin from direct API management. The plugin only needs to know how to speak to the local app-server; the server handles provider selection, authentication token retrieval, and request formatting. According to the source code in plugins/codex/scripts/lib/codex.mjs, the plugin creates a CodexAppServerClient instance to manage this connection, while the server reads configuration from ~/.codex/config.toml to determine whether to route requests to OpenAI or alternative providers.

Step-by-Step RPC Flow from Plugin to OpenAI

Step 1: Binary Invocation and Server Startup

The plugin first verifies that the codex binary is available (checked via binaryAvailable in plugins/codex/scripts/lib/process.mjs). Upon confirmation, it launches the binary, which spawns the Codex app-server. This server implements the full OpenAI API surface including models, completions, and chat endpoints.

Step 2: Client Initialization and Connection

In plugins/codex/scripts/lib/app-server.mjs, the plugin instantiates a CodexAppServerClient that connects to the server via Unix socket or TCP. This client manages the lifecycle of the connection and provides a request method for sending RPC messages.

Step 3: RPC Call Dispatch

The plugin translates Claude Code commands into specific RPC calls:

• review/start: Initiated by runAppServerReview in codex.mjs to begin a code review session
• turn/start: Initiated by runAppServerTurn to execute a model inference turn
• thread/start: Creates new conversation threads
• account/read and config/read: Used by getCodexAuthStatusFromClient to retrieve authentication state

These calls are sent as JSON-RPC messages to the app-server, which queues them for processing.

Step 4: Provider Resolution and OpenAI Forwarding

Before executing requests, the app-server calls resolveProviderConfig and formatProviderLabel (defined in codex.mjs) to parse the user's config.toml. When model_provider is set to openai, the server retrieves authentication credentials—either a ChatGPT login session or API key—stored by the Codex CLI. It then forwards the request to the appropriate OpenAI endpoints, streams the response, and notifies the plugin via server-sent events or similar notification mechanisms.

Key Source Files and Functions

The integration lives primarily in two modules:

• plugins/codex/scripts/lib/codex.mjs: Contains the high-level orchestration logic including runAppServerReview, runAppServerTurn, getCodexAuthStatus, and resolveProviderConfig. This file builds request payloads, captures turn state, and maps provider configurations to human-readable labels.

• plugins/codex/scripts/lib/app-server.mjs: Implements the CodexAppServerClient class that manages the TCP/Unix socket connection, sends RPC requests, and handles server notifications. This is the low-level transport layer between the plugin and the local Codex binary.

• plugins/codex/scripts/lib/process.mjs: Provides utility functions like binaryAvailable to verify the Codex CLI installation before attempting to spawn the app-server.

Practical Code Examples

Starting a Code Review

To initiate a review session that ultimately calls OpenAI models, use runAppServerReview:

import { runAppServerReview } from './plugins/codex/scripts/lib/codex.mjs';

await runAppServerReview(process.cwd(), {
  model: 'gpt-5.4',          // optional – defaults to config.toml
  delivery: 'inline',        // "inline" or "detached"
  target: { type: 'uncommitted' },
  onProgress: (msg) => console.log(msg)   // receives streaming notifications
});

Executing a Model Turn

For direct chat interactions, runAppServerTurn sends a turn/start RPC that the app-server forwards to OpenAI:

import { runAppServerTurn } from './plugins/codex/scripts/lib/codex.mjs';

await runAppServerTurn(process.cwd(), {
  prompt: 'Explain why the current test suite is flaky.',
  model: 'gpt-5.4-mini',
  sandbox: 'read-only',
  onProgress: (msg) => console.log(msg)
});

Checking Authentication Status

Verify whether the local Codex CLI has valid OpenAI credentials before executing expensive operations:

import { getCodexAuthStatus } from './plugins/codex/scripts/lib/codex.mjs';

const auth = await getCodexAuthStatus(process.cwd());
console.log(auth);
// Returns status indicating ChatGPT login or API key presence

Summary

• The Codex plugin never directly contacts the OpenAI API; all communication flows through the local Codex CLI.
• The plugin spawns the codex binary to start an app-server, then sends RPC calls like review/start and turn/start via a CodexAppServerClient.
• The app-server handles provider resolution by reading ~/.codex/config.toml, supporting OpenAI, Ollama, and LM Studio backends.
• Authentication credentials are managed by the Codex CLI, not the plugin, which simply queries status via getCodexAuthStatus.
• Core implementation files include plugins/codex/scripts/lib/codex.mjs for orchestration and plugins/codex/scripts/lib/app-server.mjs for transport.

Frequently Asked Questions

Does the Codex plugin store my OpenAI API key?

No. The plugin does not handle API keys directly. Authentication is managed by the locally installed Codex CLI, which stores credentials in ~/.codex/config.toml. The plugin only queries the authentication status via getCodexAuthStatus to determine if a valid OpenAI session or API key exists before initiating requests.

Can the Codex plugin work with models other than OpenAI's GPT?

Yes. The plugin supports any provider configured in the Codex CLI configuration file. According to resolveProviderConfig in codex.mjs, the app-server can route requests to Ollama, LM Studio, or other local model providers. The plugin remains agnostic to the underlying model, communicating only through the standardized RPC interface.

What happens if the Codex app-server crashes during a request?

The plugin establishes connections through CodexAppServerClient in app-server.mjs, which manages the TCP or Unix socket lifecycle. If the server becomes unavailable, subsequent RPC calls will fail with connection errors, and the plugin will surface these failures back to Claude Code. The binaryAvailable check in process.mjs helps ensure the binary exists before attempting to spawn the server, but runtime crashes would require restarting the CLI.

How does the plugin handle streaming responses from OpenAI models?

The plugin receives streaming updates via the app-server's notification system. When calling runAppServerTurn or runAppServerReview, you provide an onProgress callback that receives real-time messages containing reasoning steps, file changes, and command execution updates. The app-server handles the actual OpenAI streaming API and forwards relevant chunks to the plugin as RPC notifications.

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