How the Codex Plugin Handles Codex Authentication Status

The Codex plugin does not implement its own authentication flow; instead, it queries the locally installed Codex CLI's app-server via RPC to determine whether the user is logged in via ChatGPT, API key, or requires additional authentication.

The openai/codex-plugin-cc repository provides a VS Code extension that integrates OpenAI Codex into your editor. Understanding how it manages Codex authentication status is essential for troubleshooting connection issues and ensuring seamless access to AI-powered coding assistance.

Binary and App-Server Availability Check

Before checking authentication state, the plugin verifies that the Codex toolchain is present. In plugins/codex/scripts/lib/codex.mjs, the getCodexAvailability function confirms that the codex binary exists and that the app-server can be launched by executing codex app-server --help.

Querying Authentication via RPC

Once the binary is confirmed, the plugin establishes communication with the Codex app-server.

Account and Configuration Reads

The CodexAppServerClient class (defined in plugins/codex/scripts/lib/app-server.mjs) connects to the app-server and issues two critical RPC calls:

1. account/read (with refreshToken:false) – Determines if a login session is active and identifies the authentication method (ChatGPT or API key).
2. config/read – Retrieves the current provider configuration to check if OpenAI authentication is required.

Building the Auth Status Object

The buildAuthStatus function in codex.mjs normalizes the RPC responses into a structured object containing:

• available: Boolean indicating if the Codex binary and app-server are reachable
• loggedIn: Boolean showing whether an active session exists
• authMethod: Either "chatgpt" or "apiKey" (or null if not required)
• source: "app-server" when connected, or "availability" when the binary is missing
• detail: Human-readable description (e.g., "ChatGPT login active for user@example.com")
• requiresOpenaiAuth: Boolean indicating if the selected provider needs OpenAI credentials
• provider: The provider identifier (e.g., openai)

Error Handling and Session Expiration

When RPC calls fail—such as when an authentication session expires—the plugin catches the error and returns a status with loggedIn: false and a descriptive detail message like "authentication expired; run codex login". This allows commands to prompt users appropriately without crashing.

Command-Level Usage

All command implementations—including /codex:setup, /codex:review, and others—call getCodexAuthStatus to gate functionality. Based on the returned status, they either proceed with execution, prompt the user to run !codex login, or allow API-key-only operation for providers that do not require OpenAI authentication.

Example from codex-companion.mjs:

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
  }
}

Summary

• The plugin relies entirely on the local Codex CLI's authentication state rather than implementing its own flow.
• Authentication status is determined by querying the app-server via RPC calls to account/read and config/read.
• The buildAuthStatus function in codex.mjs normalizes responses into a standard object indicating availability, login state, method, and provider requirements.
• Commands use getCodexAuthStatus to decide whether to proceed, prompt for login, or handle expired sessions gracefully.

Frequently Asked Questions

Does the Codex plugin store my API key or login credentials?

No. The plugin does not implement its own authentication flow or store credentials. It reads the authentication state directly from your locally installed Codex CLI and app-server, which manage session tokens and API keys independently.

What happens if my Codex session expires while using the plugin?

If the RPC call to account/read fails due to an expired session, the plugin catches the error and returns loggedIn: false with a detail message indicating that authentication expired. The plugin will prompt you to run codex login to refresh your session.

Can I use the plugin with API key authentication instead of ChatGPT login?

Yes. The plugin supports both authentication methods. When buildAuthStatus detects an API key configuration via the account/read RPC response, it sets authMethod to "apiKey" and allows operation without ChatGPT login, provided the selected provider does not require OpenAI authentication.

How does the plugin handle missing Codex CLI installations?

Before attempting authentication checks, getCodexAvailability verifies that the codex binary exists and that the app-server can launch. If the binary is missing, the plugin returns an auth status with available: false and source: "availability", prompting you to install the Codex CLI first.

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