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

npm i -g @openai/codex
codex login   # or set OPENAI_API_KEY

1. Install provider and AI SDK v7

npm i ai ai-sdk-provider-codex-cli

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

npm i ai@^6 ai-sdk-provider-codex-cli@ai-sdk-v6

For AI SDK v5

npm i ai@^5.0.0 ai-sdk-provider-codex-cli@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.155.0) with "model is not supported when using Codex with a ChatGPT account". If you supply your own Codex CLI (global install or custom codexPath), check it with codex --version and upgrade if needed.

npm i -g @openai/codex@latest

Quick Start

Exec provider (codexExec) — process-per-call

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

const model = codexExec('gpt-6-astra', {
  allowNpx: true,
  skipGitRepoCheck: true,
  approvalMode: 'on-request',
  sandboxMode: 'workspace-write',
});

const { text } = await generateText({
  model,
  prompt: 'Reply with a single word: hello.',
});
console.log(text);

App-server provider (createCodexAppServer) — persistent process

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

const provider = createCodexAppServer({
  defaultSettings: {
    minCodexVersion: '0.156.0',
    autoApprove: false,
    personality: 'pragmatic',
  },
});

const { textStream } = await streamText({
  model: provider('gpt-6-astra'),
  prompt: 'Write two short lines of encouragement.',
});
for await (const chunk of textStream) process.stdout.write(chunk);

await provider.close();

App-server stateful threads (optional)

By default, codexAppServer is stateless (new ephemeral thread per call). To continue a prior conversation across calls, start a persistent thread and then pass its threadId in providerOptions['codex-app-server'].

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

const provider = createCodexAppServer();

const first = await generateText({
  model: provider('gpt-6-astra'),
  prompt: 'Start a migration checklist.',
  providerOptions: {
    'codex-app-server': { threadMode: 'persistent' },
  },
});

const threadId = first.finalStep.providerMetadata?.['codex-app-server']?.threadId;

const second = await generateText({
  model: provider('gpt-6-astra'),
  prompt: 'Continue from step 2.',
  providerOptions: {
    'codex-app-server': { threadId },
  },
});

await provider.close();

Object generation (Zod)

import { generateObject } from 'ai';
import { z } from 'zod';
import { codexExec } from 'ai-sdk-provider-codex-cli';…