# How the Codex Plugin Interacts with Codex Authentication State

> Discover how the Codex plugin works with Codex authentication. It reuses your existing state by querying the local Codex CLI app-server via RPC, avoiding its own authentication flow.

- Repository: [OpenAI/codex-plugin-cc](https://github.com/openai/codex-plugin-cc)
- Tags: internals
- Published: 2026-07-18

---

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

```js
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`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/scripts/lib/codex.mjs)*

### Gating Setup Commands

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

```js
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`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/scripts/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:

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

```

*Source: [`codex-companion.mjs`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/scripts/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.