How the Codex Plugin Interacts with Codex Authentication State

The Codex plugin does not implement its own authentication flow; instead, it queries the locally installed Codex CLI's app-server via RPC to reuse your existing authentication state.

The openai/codex-plugin-cc extension operates as a transparent layer over your existing Codex command-line tool. When determining how to interact with Codex authentication state, the plugin neither stores credentials nor implements login flows; rather, it communicates with the Codex app-server to inspect your current session status and provider configuration.

No Built-in Authentication Flow

Unlike extensions that manage API keys internally, the Codex plugin re-uses the authentication state of the locally installed Codex CLI and its app-server component. This design ensures that any login session you've established through codex login—whether via ChatGPT authentication or API key—is immediately available to the plugin without duplicate configuration.

Authentication Verification Pipeline

The plugin verifies your authentication status through a three-stage RPC-based process defined in plugins/codex/scripts/lib/codex.mjs.

Binary and App-Server Availability

Before issuing auth queries, the plugin confirms that the codex binary is present and that the app-server can be launched. The getCodexAvailability function validates this by executing codex app-server --help. If the binary is missing, the plugin returns an available: false status and advises installing the Codex CLI.

RPC Communication with the App-Server

When the binary is confirmed, the plugin creates a CodexAppServerClient (implemented in plugins/codex/scripts/lib/app-server.mjs) and establishes a connection via CodexAppServerClient.connect. The client then issues two critical RPC calls:

• account/read (with refreshToken: false) – Determines whether a user is logged in and identifies the login method (ChatGPT or API-key).
• config/read – Retrieves the current provider configuration to check if OpenAI authentication is required.

Constructing the Auth Status Object

The raw RPC responses are normalized by buildAuthStatus into a structured object consumed by all plugin commands. This object contains the following fields:

• available: true if the Codex binary and app-server are reachable.
• loggedIn: true when an active login session exists.
• authMethod: Returns "chatgpt" or "apiKey" (or null when authentication is not required).
• requiresOpenaiAuth: true if the selected provider mandates OpenAI authentication; false for providers that operate without it.
• provider: The provider identifier (e.g., openai).
• source: "app-server" when derived from RPC calls, or "availability" when the binary is missing.
• detail: Human-readable description (e.g., "ChatGPT login active for user@example.com").

Handling Expired Sessions

If the app-server RPC fails—such as when a session has expired—the plugin catches the error and returns a degraded auth status with loggedIn: false and a descriptive detail field (e.g., "authentication expired; run codex login"). This allows commands to gracefully prompt users to re-authenticate via !codex login rather than failing with technical stack traces.

Implementation in Plugin Commands

All command implementations—including /codex:setup, /codex:review, and others—call getCodexAuthStatus to gate their functionality. Based on the returned status, they either proceed with the operation, prompt for installation, or advise running codex login.

Checking Authentication from a Custom Command

The following example demonstrates how to inspect authentication state using the core utility function:

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

async function showAuth(cwd) {
  const auth = await getCodexAuthStatus(cwd);
  console.log(`Codex auth – logged in: ${auth.loggedIn}`);
  console.log(`Method: ${auth.authMethod ?? "none"}`);
  console.log(`Detail: ${auth.detail}`);
}

Source: codex.mjs

Gating Setup Commands

The /codex:setup command uses the auth status to determine the next steps:

import { getCodexAuthStatus } from "./lib/codex.mjs";

export async function runSetup(cwd) {
  const auth = await getCodexAuthStatus(cwd);
  if (!auth.available) {
    // suggest installing Codex
  } else if (!auth.loggedIn) {
    // advise the user to run `!codex login`
  } else {
    // ready to go
  }
}

Source: codex-companion.mjs

Prompting for Login When Required

When a provider requires OpenAI authentication but the user is not logged in, the companion script generates specific guidance:

if (!authStatus.loggedIn && authStatus.requiresOpenaiAuth) {
  nextSteps.push("Run `!codex login`.");
}

Source: codex-companion.mjs

Summary

• The openai/codex-plugin-cc plugin delegates authentication to the local Codex CLI rather than implementing its own flow.
• It verifies availability via getCodexAvailability before establishing an RPC connection through CodexAppServerClient.
• The getCodexAuthStatus function normalizes session data from account/read and config/read RPC calls into a standardized status object.
• All plugin commands use this status to determine whether to proceed, prompt for login, or request CLI installation.
• Expired sessions are handled gracefully with actionable error messages directing users to run codex login.

Frequently Asked Questions

Does the plugin store my API keys or ChatGPT credentials?

No. The plugin never stores authentication credentials internally. It queries the Codex app-server to read your existing CLI authentication state, making it a transparent pass-through layer that relies entirely on your local Codex installation.

What happens if the Codex CLI is not installed?

If the plugin cannot locate the codex binary via getCodexAvailability, it returns an auth status with available: false and source: "availability". Commands then prompt you to install the Codex CLI before attempting any authentication-dependent operations.

How does the plugin distinguish between ChatGPT login and API key authentication?

The account/read RPC call returns the active login method, which buildAuthStatus maps to the authMethod field. This field contains either "chatgpt" for OAuth-based sessions or "apiKey" for key-based authentication, allowing the plugin to display method-specific messaging.

Which source files handle the core authentication logic?

The primary logic resides in plugins/codex/scripts/lib/codex.mjs (containing getCodexAuthStatus and buildAuthStatus), with the RPC client implemented in plugins/codex/scripts/lib/app-server.mjs. Command orchestration in plugins/codex/scripts/codex-companion.mjs consumes these utilities to drive user-facing behavior.

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