AI SDK Provider for OpenAI Codex CLI

1.1.0 · active · verified Wed Apr 22

The `ai-sdk-provider-codex-cli` package offers a community-maintained integration for Vercel's AI SDK v6, enabling access to OpenAI's Codex CLI and its GPT-5 class models (e.g., `gpt-5.1`, `gpt-5.2`, `gpt-5.3-codex`, `gpt-5.2-codex-max`) using an existing ChatGPT Plus/Pro subscription. Currently at version 1.1.0, the library is actively developed, with recent releases focusing on AI SDK v6 compatibility and new features like the `createCodexAppServer` persistent JSON-RPC client. It provides two primary modes: `codexExec` for a new process per call, and `createCodexAppServer` for a long-lived process with advanced session controls like `injectMessage` and `interrupt`. This Node-only provider works with `generateText`, `streamText`, and `generateObject` functions, and authenticates via `codex login` or `OPENAI_API_KEY`. Its key differentiator is leveraging the local Codex CLI for direct, granular control over model execution and sandboxing, providing an alternative to direct API integrations for users with existing ChatGPT subscriptions.

Common errors

```
No prompt provided via stdin
```
cause Using images with `streamText` caused argument parsing issues where Codex CLI's `--image` flag consumed the prompt text as an additional image path.

fix Upgrade to `ai-sdk-provider-codex-cli@1.0.4` or later (or `v0.7.3` for AI SDK v5). These versions add an explicit `'--'` separator before the prompt when images are present.
```
SyntaxError: Invalid or unexpected token
```
cause When providing an explicit `codexPath` to a native executable (e.g., Homebrew's `/opt/homebrew/bin/codex`), the provider incorrectly attempted to execute it via `node`.

fix Upgrade to `ai-sdk-provider-codex-cli@1.0.3` or later (or `v0.7.2` for AI SDK v5). These versions correctly distinguish between JS entrypoints and native executables.

Warnings

breaking Version 1.0.0 introduced breaking changes related to the migration to AI SDK v6, updating interfaces from `LanguageModelV2` to `LanguageModelV3`, `ProviderV2` to `ProviderV3`, and changing the format of `finishReason` and `Usage` objects.
Fix: Review the AI SDK v6 migration guide. Update your code to conform to the new `LanguageModelV3` interface, adapt `finishReason` checks from `'stop'` to `{ unified: 'stop', raw: undefined }`, and adjust usage metrics parsing for the new nested structure (e.g., `inputTokens.total`, `outputTokens.total`).
breaking The `includePlanTool` setting was removed in v1.0.1 because the corresponding `--include-plan-tool` CLI flag was deprecated and removed in Codex CLI 0.48.0 (October 2025). The plan tool is now always enabled by default.
Fix: Remove any `includePlanTool: true` or `false` settings from your provider configuration. The functionality is now implicit.
gotcha This provider requires Codex CLI version `>= 0.105.0` for full support of both `codexExec` and `createCodexAppServer` modes. Older versions may lack certain features or exhibit unexpected behavior.
Fix: Ensure your global Codex CLI installation is up to date by running `npm i -g @openai/codex@latest` and verifying with `codex --version`. The optional `@openai/codex` dependency pulls a compatible version automatically, but a global install may need manual update.
gotcha This package maintains separate versions for AI SDK v5 and v6 compatibility. Using the wrong version for your `ai` package installation can lead to type errors or runtime issues.
Fix: For AI SDK v6 (default), install `ai-sdk-provider-codex-cli` with `npm i ai ai-sdk-provider-codex-cli`. For AI SDK v5, install `ai-sdk-provider-codex-cli@ai-sdk-v5 ai@^5.0.0`.
gotcha On Windows, long prompts or those containing special characters (e.g., Chinese text, newlines, backticks) could fail due to command line length limits or shell escaping issues prior to v1.0.5. Prompts were passed as command line arguments.
Fix: Upgrade to `ai-sdk-provider-codex-cli@1.0.5` or later. This version fixes the issue by passing prompts via stdin instead of command line arguments.

Install

npm install ai-sdk-provider-codex-cli npm
yarn add ai-sdk-provider-codex-cli yarn
pnpm add ai-sdk-provider-codex-cli pnpm

Imports

codexExec
wrong:
```
const { codexExec } = require('ai-sdk-provider-codex-cli');
```
correct:
```
import { codexExec } from 'ai-sdk-provider-codex-cli';
```
The AI SDK v6 ecosystem primarily uses ESM. CommonJS `require` syntax is not supported in recent versions.

createCodexAppServer

wrong:

import createCodexAppServer from 'ai-sdk-provider-codex-cli/app-server';

correct:

import { createCodexAppServer } from 'ai-sdk-provider-codex-cli';

Both providers are named exports from the main package entrypoint.

generateText
wrong:
```
import { generateText } from 'ai-sdk-provider-codex-cli';
```
correct:
```
import { generateText } from 'ai';
```
Core AI SDK functions like `generateText` and `streamText` are imported directly from the `ai` package, not from the provider itself.

Quickstart

Demonstrates how to use the `codexExec` provider with `generateText` to get a simple text response from a GPT-5 class model, showing basic configuration and token usage.

import { generateText } from 'ai';
import { codexExec } from 'ai-sdk-provider-codex-cli';

async function main() {
  // Ensure Codex CLI is installed and authenticated: `npm i -g @openai/codex && codex login`
  // You can also pass OPENAI_API_KEY as an environment variable.

  const model = codexExec('gpt-5.3-codex', {
    // allowNpx: true, // Set to true to allow npx usage if codex is not globally installed
    // skipGitRepoCheck: true, // Optional: skip git repository checks for local scripts
    approvalMode: 'on-failure', // Automatically approve successful executions, prompt on failure
    sandboxMode: 'workspace-write', // Allow Codex to write to the current workspace
    codexPath: process.env.CODEX_CLI_PATH ?? undefined // Optional: specify custom path to codex executable
  });

  const { text, usage } = await generateText({
    model,
    messages: [
      { role: 'user', content: 'Reply with a single, common greeting word.' }
    ],
  });

  console.log('Generated Text:', text);
  console.log('Token Usage:', usage);
}

main().catch(console.error);

view raw JSON →