ai-sdk-provider-codex-cli weekly downloads statistics

AI SDK Provider for Codex CLI

A community provider for Vercel AI SDK v7 that integrates OpenAI's Codex CLI (for example gpt-6-astra) using your ChatGPT Plus/Pro subscription. Available model slugs follow whatever your installed Codex CLI exposes — use listModels() / provider.listModels() to discover them.

This package ships two provider modes:

• codexExec: non-interactive codex exec (spawn a new process per call) • codexAppServer: persistent codex app-server JSON-RPC client (shared process, true delta streaming, optional stateful threads) • Works with generateText, streamText, and generateObject • Uses ChatGPT OAuth from codex login (tokens in ~/.codex/auth.json) or OPENAI_API_KEY • Node-only (spawns a local process); supports CI and local dev • Requires Node.js >= 22; published as an ESM-only package • v2.0.0: AI SDK v7 migration with the native LanguageModelV4 provider spec (package line 2.x) • v1.0.0: AI SDK v6 migration with the LanguageModelV3 interface (now on the ai-sdk-v6 tag)

Version Compatibility

| Package line | AI SDK | npm tag | Git branch | Status |

| 2.x | v7 | latest, ai-sdk-v7 | main | Active development | | 1.x | v6 | ai-sdk-v6 | ai-sdk-v6 | Maintenance | | 0.7.x | v5 | ai-sdk-v5 | ai-sdk-v5 | Maintenance / critical fixes | | 0.1.0-ai-sdk-v4 | v4 | ai-sdk-v4 | ai-sdk-v4 | Frozen |

Installation

For AI SDK v7 (default)

1. Install and authenticate Codex CLI

2. Install provider and AI SDK v7

Requirements: Node.js >= 22. This package is ESM-only (no CommonJS build); load it with import (or dynamic import() from CJS).

For AI SDK v6

For AI SDK v5

⚠️ Codex CLI Version: Requires the current stable Codex CLI 0.156.x for full support of both provider modes (codexExec and codexAppServer). This package pins its optional @openai/codex dependency to ^0.156.1, the latest non-alpha release line validated for this release line. gpt-6-sol (used by the examples) is rejected by older CLIs (= 0.139) • persistExtendedHistory: request extended thread history persistence • threadMode: stateless (default) or persistent automatic thread reuse • resume: shorthand to resume an existing thread id • onSessionCreated: receive a session object for injectMessage() / interrupt()

Per-call app-server overrides use providerOptions['codex-app-server'] (for example threadId, threadMode, includeRawChunks, personality, approvalPolicy, sandboxPolicy, serverRequests, configOverrides). Raw chunk emission can also be requested per call with the standard AI SDK v7 option include: { rawChunks: true }.

Additional app-server helpers:

• listModels(): query available models via a temporary app-server process (or use provider.listModels() to query through an existing provider/client) • tool(), createLocalMcpServer(), createSdkMcpServer(): define and expose local MCP tools

Local MCP security defaults:

• createLocalMcpServer() binds to loopback hosts by default and rejects non-loopback host values unless you set allowNonLoopbackHost: true. • createLocalMcpServer() generates a per-server bearer token and expects Authorization: Bearer on direct HTTP calls. The token is available at server.config.bearerToken. • createSdkMcpServer() propagates this auth config automatically, so provider-level MCP wiring works without extra manual headers. • Without cacheKey, SDK MCP server/tool function identity participates in persistent keying to avoid conflating closure-dependent tool behavior. • Use createSdkMcpServer({ cacheKey }) when you intentionally recreate equivalent SDK MCP definitions per call and want stable persistent model reuse.

Model Parameters & Advanced Options

Control reasoning effort, verbosity, and advanced Codex features at model creation time:

Nested override objects are flattened to dotted keys (e.g., the example above emits -c sandbox_workspace_write.network_access=true). Arrays are serialized to JSON strings. MCP server env/header objects flatten the same way (e.g., mcp_servers.docs.http_headers.x-tenant=acme).

Per-call overrides via providerOptions

Override these parameters for individual AI SDK calls using the providerOptions map. Per-call values take precedence over constructor defaults while leaving other settings intact.

Precedence: providerOptions['codex-cli'] > top-level reasoning call option > constructor CodexCliSettings > Codex CLI defaults.

The AI SDK v7 top-level reasoning option ('none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh') maps directly to Codex reasoning effort in both provider modes; provider-specific effort options (reasoningEffort for exec, effort for app-server) win when both are set, and 'provider-default' leaves your configured default untouched. The newer Codex levels 'max' and 'ultra' (Codex CLI >= 0.149, e.g. gpt-6-astra) are not part of the AI SDK union, so set them through the provider-specific options.

App-server per-call overrides use providerOptions['codex-app-server']:

Zod Compatibility

• Peer dependency: zod@^4.1.8 (Zod 4 only; Zod 3 is not supported)

Limitations

• Node ≥ 22, ESM-only, local process only (no Edge) • Codex --experimental-json mode emits events rather than streaming deltas; streaming typically yields a final chunk. The CLI provides the final assistant text in the item.completed event, which this provider reads and emits at the end. • Some AI SDK parameters are unsupported by Codex CLI (e.g., temperature/topP/penalties); the provider surfaces warnings and ignores them

JSON Schema Limitations

⚠️ Important: OpenAI strict mode has limitations:

• Optional fields NOT supported: All fields must be required (no .optional()) • Format validators stripped: .email(), .url(), .uuid() are removed (use descriptions instead) • Pattern validators stripped: .regex() is removed (use descriptions instead)

See LIMITATIONS.md for comprehensive details and migration guidance.

Disclaimer

This is a community provider and not an official OpenAI or Vercel product. You are responsible for complying with all applicable terms and ensuring safe usage.…

Description from the npm listing.