How the Codex Plugin Manages Authentication and Reuses Existing Credentials

The Codex plugin does not implement its own authentication flow; instead, it detects and reuses the authentication state of the locally installed Codex CLI through the getCodexAuthStatus function.

The openai/codex-plugin-cc repository provides a code review plugin that integrates deeply with the OpenAI Codex ecosystem. Rather than maintaining separate credential storage or login mechanisms, the plugin acts as a thin wrapper around the Codex CLI's existing authentication infrastructure, automatically detecting browser sessions, API keys, and environmental configurations already established on the developer's machine.

Detecting Codex CLI Availability and Auth State

The authentication detection process begins in the companion script at plugins/codex/scripts/codex-companion.mjs. This script first verifies that the codex binary is present on the host system before attempting to query its authentication status.

Once the CLI is confirmed available, the script imports getCodexAuthStatus from plugins/codex/scripts/lib/codex.mjs. This function instantiates a CodexClient with the current working directory and queries the CLI for active session information.

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

async function isReady(cwd) {
  const auth = await getCodexAuthStatus(cwd);
  console.log(`Logged in: ${auth.loggedIn}`);
  console.log(`Method: ${auth.authMethod}`);
  console.log(`Source: ${auth.source}`);
  
  // Ready if Codex is installed AND (logged in OR provider doesn't need OpenAI auth)
  return auth.loggedIn || auth.requiresOpenaiAuth === false;
}

Interpreting the Authentication Status Object

The getCodexAuthStatus function returns a structured object containing several critical fields that determine whether the plugin can execute operations. According to the source code in plugins/codex/scripts/lib/codex.mjs (lines 786-842 and 848-861), this object includes:

• loggedIn: Boolean indicating whether the CLI reports a valid active session
• authMethod: String value of "chatgpt" (browser session), "apiKey" (environment variable), or null when the provider operates without OpenAI authentication
• source: Origin of the credentials, either "codex" for standard CLI login or "app-server" when the plugin trusts an externally supplied API key
• detail: Human-readable description such as "API key configured (unverified)"
• requiresOpenaiAuth: Boolean indicating whether the selected provider requires OpenAI credentials versus self-hosted service operation

The companion script uses these fields to determine readiness and generate appropriate user guidance.

App-Server Configurations and Graceful Fallbacks

When the plugin operates behind an app-server that supplies an API key, the authentication logic implements a graceful fallback mechanism. In this configuration, the source field reports "app-server" and authMethod returns "apiKey".

Even when the underlying Codex CLI reports loggedIn === false, the plugin considers the authentication status ready because it trusts the externally supplied key. This behavior is validated in the test suite at tests/runtime.test.mjs, which asserts that configurations with authMethod === "apiKey" and source === "app-server" proceed without requiring manual CLI login.

The companion script implements this logic to decide whether to suggest login commands:

const authStatus = await getCodexAuthStatus(cwd);
if (codexStatus.available && !authStatus.loggedIn && authStatus.requiresOpenaiAuth) {
  nextSteps.push(
    "If browser login is blocked, retry with `!codex login --device-auth` or `!codex login --with-api-key`."
  );
}

Session Refresh and Error Propagation

The plugin handles stale sessions through a refreshable authentication flow. When encountering expired credentials, the system can re-run the auth check after triggering a Codex login refresh, allowing continued operation without manual intervention.

Error handling propagates directly from the CLI to the user. If the Codex binary returns an authentication error such as "authentication expired; run codex login", the plugin surfaces this exact message without transformation. The test fixtures in tests/fake-codex-fixture.mjs demonstrate this behavior through the auth-run-fails scenario, ensuring users receive transparent, actionable error messages.

Summary

• The Codex plugin delegates all authentication to the local Codex CLI, implementing no independent credential storage or login flows.
• getCodexAuthStatus in plugins/codex/scripts/lib/codex.mjs creates a CodexClient and parses CLI output to determine session validity.
• The auth status object returns loggedIn, authMethod, source, detail, and requiresOpenaiAuth fields to guide execution decisions.
• App-server mode allows operation with externally supplied API keys even when the CLI reports no active session.
• Staleness handling supports refreshable logins, while error propagation surfaces CLI messages directly to users.

Frequently Asked Questions

How does the Codex plugin store API keys and credentials?

The plugin does not store API keys or credentials internally. According to the source code in openai/codex-plugin-cc, all authentication state resides with the Codex CLI installed on the host machine. The plugin merely queries this existing state through the getCodexAuthStatus function and acts as a read-only consumer of the CLI's authentication infrastructure.

Can the plugin run without logging into the Codex CLI?

Yes, under specific conditions. If the plugin connects to an app-server that provides an API key (indicated by source === "app-server" and authMethod === "apiKey"), it operates without requiring the local Codex CLI to show loggedIn === true. Additionally, if the configured provider sets requiresOpenaiAuth to false, the plugin executes without any OpenAI authentication.

What happens when the Codex CLI session expires?

When the CLI reports an expired session, the plugin surfaces the exact error message to the user, such as "authentication expired; run codex login". The test suite at tests/runtime.test.mjs confirms that the plugin supports refreshable authentication flows, allowing the system to re-check status after the user refreshes their CLI login without requiring a full restart of the plugin environment.

Which source files handle the authentication detection logic?

The primary authentication logic resides in plugins/codex/scripts/lib/codex.mjs (specifically lines 786-861), which implements the getCodexAuthStatus function and CodexClient class. The companion script at plugins/codex/scripts/codex-companion.mjs consumes this status to determine readiness, while tests/runtime.test.mjs and tests/fake-codex-fixture.mjs provide test coverage for various authentication scenarios.

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