Registry / llm-agents / ai-sdk-provider-codex-cli

ai-sdk-provider-codex-cli

library1.1.0jsnpmunverified

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.

llm-agents ai-ml http-networking

npm install ai-sdk-provider-codex-cli

github ↗package ↗

INSTALL

IMPORT

SIG · AI-SDK-PROVIDER-CO

ai-sdk-provider-codex-cli

llm-agentsjavascriptv1.1.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

codexExec

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

✗ const { codexExec } = require('ai-sdk-provider-codex-cli');

The AI SDK v6 ecosystem primarily uses ESM. CommonJS `require` syntax is not supported in recent versions.

createCodexAppServer

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

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

Both providers are named exports from the main package entrypoint.

generateText

✓ import { generateText } from 'ai';

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

Core AI SDK functions like `generateText` and `streamText` are imported directly from the `ai` package, not from the provider itself.

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);

codex --version

Debug

Known issues

breakingVersion 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`).

affects: >=1.0.0

breakingThe `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.

affects: >=1.0.1

gotchaThis 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.

affects: >=0.0.0

gotchaThis 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`.

affects: >=0.0.0

gotchaOn 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.

affects: <1.0.5

Errors

Common errors & fixes

No prompt provided via stdin

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

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.

Upgrade

Version history

1.1.0latest on npm

Audit

Dependencies

airequiredRequired peer dependency for AI SDK functionalities.

zodrequiredPeer dependency used for schema validation within the AI SDK and potentially for internal types.

@openai/codexoptionalOptional dependency that pulls a compatible version of the Codex CLI; however, users might install it globally or specify a custom path.

Agent activity

53 hits · last 30 days

node

Perplexity

OpenAI (training)

Resources

githubhttps://github.com/ben-vargas/ai-sdk-provider-codex-cli ↗

packagehttps://www.npmjs.com/package/ai-sdk-provider-codex-cli ↗