{"id":17415,"library":"ai-sdk-provider-codex-cli","title":"AI SDK Provider for OpenAI Codex CLI","description":"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.","status":"active","version":"1.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/ben-vargas/ai-sdk-provider-codex-cli","tags":["javascript","ai-sdk","codex","openai","cli","language-model","gpt-5","gpt-5.1","gpt-5.3-codex","typescript"],"install":[{"cmd":"npm install ai-sdk-provider-codex-cli","lang":"bash","label":"npm"},{"cmd":"yarn add ai-sdk-provider-codex-cli","lang":"bash","label":"yarn"},{"cmd":"pnpm add ai-sdk-provider-codex-cli","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required peer dependency for AI SDK functionalities.","package":"ai","optional":false},{"reason":"Peer dependency used for schema validation within the AI SDK and potentially for internal types.","package":"zod","optional":false},{"reason":"Optional dependency that pulls a compatible version of the Codex CLI; however, users might install it globally or specify a custom path.","package":"@openai/codex","optional":true}],"imports":[{"note":"The AI SDK v6 ecosystem primarily uses ESM. CommonJS `require` syntax is not supported in recent versions.","wrong":"const { codexExec } = require('ai-sdk-provider-codex-cli');","symbol":"codexExec","correct":"import { codexExec } from 'ai-sdk-provider-codex-cli';"},{"note":"Both providers are named exports from the main package entrypoint.","wrong":"import createCodexAppServer from 'ai-sdk-provider-codex-cli/app-server';","symbol":"createCodexAppServer","correct":"import { createCodexAppServer } from 'ai-sdk-provider-codex-cli';"},{"note":"Core AI SDK functions like `generateText` and `streamText` are imported directly from the `ai` package, not from the provider itself.","wrong":"import { generateText } from 'ai-sdk-provider-codex-cli';","symbol":"generateText","correct":"import { generateText } from 'ai';"}],"quickstart":{"code":"import { generateText } from 'ai';\nimport { codexExec } from 'ai-sdk-provider-codex-cli';\n\nasync function main() {\n  // Ensure Codex CLI is installed and authenticated: `npm i -g @openai/codex && codex login`\n  // You can also pass OPENAI_API_KEY as an environment variable.\n\n  const model = codexExec('gpt-5.3-codex', {\n    // allowNpx: true, // Set to true to allow npx usage if codex is not globally installed\n    // skipGitRepoCheck: true, // Optional: skip git repository checks for local scripts\n    approvalMode: 'on-failure', // Automatically approve successful executions, prompt on failure\n    sandboxMode: 'workspace-write', // Allow Codex to write to the current workspace\n    codexPath: process.env.CODEX_CLI_PATH ?? undefined // Optional: specify custom path to codex executable\n  });\n\n  const { text, usage } = await generateText({\n    model,\n    messages: [\n      { role: 'user', content: 'Reply with a single, common greeting word.' }\n    ],\n  });\n\n  console.log('Generated Text:', text);\n  console.log('Token Usage:', usage);\n}\n\nmain().catch(console.error);","lang":"typescript","description":"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."},"warnings":[{"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`).","message":"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.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Remove any `includePlanTool: true` or `false` settings from your provider configuration. The functionality is now implicit.","message":"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.","severity":"breaking","affected_versions":">=1.0.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.0.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=0.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<1.0.5"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","cause":"Using images with `streamText` caused argument parsing issues where Codex CLI's `--image` flag consumed the prompt text as an additional image path.","error":"No prompt provided via stdin"},{"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.","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`.","error":"SyntaxError: Invalid or unexpected token"}],"ecosystem":"npm","meta_description":null}