v0.7.0

What's New

Multimodal Image Support

Added support for passing images to Codex CLI via the --image flag.

Supported formats:

• Base64 data URLs (data:image/png;base64,...)
• Base64 strings
• Buffer / Uint8Array / ArrayBuffer

Example:

import { codexCli } from 'ai-sdk-provider-codex-cli';
import { generateText } from 'ai';
import { readFileSync } from 'fs';

const model = codexCli('gpt-5.1-codex');
const imageBuffer = readFileSync('./screenshot.png');

const { text } = await generateText({
  model,
  messages: [{
    role: 'user',
    content: [
      { type: 'text', text: 'What do you see?' },
      { type: 'image', image: imageBuffer, mimeType: 'image/png' },
    ],
  }],
});

Notes:

• HTTP/HTTPS URLs are not supported (images must be provided as binary data)
• Images are written to temp files and cleaned up after each request
• Multiple images per request are supported

Full Changelog: v0.5.2...v0.7.0

v0.6.0

[0.6.0] - 2025-11-21

Added

• First-class MCP configuration: mcpServers and rmcpClient settings map directly to Codex CLI MCP config keys (stdio + HTTP/RMCP), with per-call overrides, validation, and tests.
• Documentation and examples: README, docs, and examples now show MCP server setup without relying on configOverrides.
• Add-dirs support: New addDirs setting (array of strings) to expose additional directories to the model context (maps to --add-dir).

Fixed

• File Preservation: The outputLastMessageFile is no longer deleted after execution if the user explicitly provided the path. Auto-generated temp files are still cleaned up.

v0.5.2 - gpt-5.1-codex-max & xhigh reasoning support

🚀 What's New

Support for OpenAI's flagship gpt-5.1-codex-max model and its exclusive xhigh reasoning effort level.

✨ Features

• New Model: gpt-5.1-codex-max - OpenAI's most capable coding model
• Extended Reasoning: xhigh reasoning effort level for maximum reasoning depth
• Updated Dependencies: Bumped @openai/codex to ^0.60.1 for full compatibility

📝 Model-Specific Reasoning Effort Levels

Model	Supported Reasoning Efforts
gpt-5.1	low, medium, high
gpt-5.1-codex	low, medium, high
gpt-5.1-codex-max	low, medium, high, xhigh ⭐
gpt-5.1-codex-mini	medium, high

📦 Installation

npm install [email protected]

Version Requirement: Requires Codex CLI >= 0.60.0 for gpt-5.1-codex-max and xhigh support.

npm install -g @openai/codex@latest

💡 Usage Example

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

const model = codexCli('gpt-5.1-codex-max', {
  reasoningEffort: 'xhigh', // Maximum reasoning depth
  allowNpx: true,
  skipGitRepoCheck: true,
});

const result = await generateText({
  model,
  prompt: 'Explain the architectural tradeoffs...',
});

🔧 Changes

• Added xhigh to ReasoningEffort type across all schema definitions
• Updated @openai/codex dependency to ^0.60.1
• Added test coverage for xhigh parameter validation
• Updated documentation and examples to reflect new capabilities
• Added gpt-5.1-codex-max to package.json keywords

🧪 Testing

• ✅ All 36 tests passing
• ✅ Build successful (ESM + CJS + DTS)
• ✅ Added unit test for xhigh validation

📚 Documentation Updates

• README.md: Updated model list, version requirements, and configuration examples
• docs/ai-sdk-v5/configuration.md: Documented model-specific reasoning effort capabilities
• examples/generate-object-advanced.mjs: Updated to demonstrate gpt-5.1-codex-max with xhigh

⚠️ Breaking Changes

None - purely additive feature. Fully backward compatible.

🔗 Full Changelog

Full Changelog: v0.5.1...v0.5.2

v0.5.1 - GPT-5.1 Model Support

🎯 GPT-5.1 Model Family Support

This release updates documentation and examples to support OpenAI's new GPT-5.1 model family while maintaining backward compatibility with legacy GPT-5 slugs.

✨ New Model Slugs

The provider now officially documents support for three GPT-5.1 model variants:

• gpt-5.1 - General GPT-5.1 model for broad use cases
• gpt-5.1-codex - Codex-optimized GPT-5.1 for coding tasks
• gpt-5.1-codex-mini - Lightweight Codex variant for faster responses

Note: Legacy gpt-5 and gpt-5-codex slugs remain fully compatible for existing workflows.

📚 Documentation Updates

• Updated all examples (20+ files) to use GPT-5.1 model slugs
• Clarified reasoning effort levels for GPT-5.1:
  • Available: low, medium, high
  • Not available: minimal (server-side rejection)
• Documented modelVerbosity behavior:
  • Works with gpt-5.1 (general model)
  • Does not work with Codex-specific slugs (gpt-5.1-codex, gpt-5.1-codex-mini)
• Enhanced configuration guide with model-specific parameter compatibility
• Updated README with GPT-5.1 guidance and examples

🔧 Maintenance

• Bumped package version to 0.5.1
• Updated dev dependencies (@types/node, ai, zod) for clean npm audit
• Refreshed lockfile with latest compatible versions
• Added GPT-5.1 keywords to package.json for better discoverability

📦 Installation

npm install [email protected]

🚀 Quick Start with GPT-5.1

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

const model = codexCli('gpt-5.1-codex', {
  allowNpx: true,
  skipGitRepoCheck: true,
});

const { text } = await generateText({
  model,
  prompt: 'Explain the differences between GPT-5 and GPT-5.1',
});

console.log(text);

🔄 Backward Compatibility

All existing code using gpt-5 or gpt-5-codex slugs will continue to work without modification. You can migrate to GPT-5.1 slugs at your own pace.

📖 Full Changelog

See PR #7 for detailed changes: #7

v0.5.0 - Comprehensive Logging System

🎉 What's New

This release adds a comprehensive logging system with configurable verbosity and custom logger support for better debugging and production use.

✨ Features Added

• Four-level logging: debug, info, warn, error
• Verbose mode: Control debug/info log visibility via verbose setting (default: false for clean production output)
• Custom logger support: Integrate with Winston, Pino, Datadog, Sentry, and other logging frameworks
• Silent mode: Set logger: false to disable all logging
• Default logger with level tags: [DEBUG], [INFO], [WARN], [ERROR] prefixes for clarity

📝 Examples

Four new comprehensive examples demonstrating different logging modes:

• examples/logging-default.mjs - Default non-verbose mode (warn/error only)
• examples/logging-verbose.mjs - Verbose mode with full debug visibility
• examples/logging-custom-logger.mjs - Custom logger integration
• examples/logging-disabled.mjs - Complete logging suppression

📚 Documentation

• Comprehensive logging configuration in docs/ai-sdk-v5/guide.md
• Parameter documentation in docs/ai-sdk-v5/configuration.md
• Logging examples section in examples/README.md
• New logging section in main README

⚠️ Potentially Breaking Changes

Who is affected: Only users with custom Logger implementations (estimated <5% of users).

What changed: The Logger interface now requires 4 methods instead of 2:

• debug(message: string): void - NEW - for detailed execution tracing (verbose mode only)
• info(message: string): void - NEW - for general flow information (verbose mode only)
• warn(message: string): void - existing
• error(message: string): void - existing

Migration for Custom Logger Users

// Before (v0.4.x) ❌
const logger = {
  warn: (msg) => myLogger.warn(msg),
  error: (msg) => myLogger.error(msg),
};

// After (v0.5.0+) ✅
const logger = {
  debug: (msg) => myLogger.debug(msg), // Add this
  info: (msg) => myLogger.info(msg),   // Add this
  warn: (msg) => myLogger.warn(msg),
  error: (msg) => myLogger.error(msg),
};

Most users are unaffected:

• No custom logger = no changes needed ✅
• logger: false = no changes needed ✅
• Default logger automatically handles all log levels ✅

📊 Other Changes

• Default logger now includes level tags - All log messages prefixed with [DEBUG], [INFO], [WARN], or [ERROR]
  • May affect applications parsing console output (use custom logger or logger: false if needed)
• Non-verbose mode (default) only shows warn/error messages for cleaner production logs

🧪 Testing

• All new settings (verbose, logger) are optional with safe defaults
• 7 new unit tests covering logger functionality (all passing)
• Comprehensive test coverage for all logging scenarios and custom logger implementations
• Supports custom logging integrations (Winston, Pino, Datadog, Sentry, etc.)

---

Full Changelog: v0.4.0...v0.5.0

v0.4.0: Comprehensive Model Parameter Control

🎉 Comprehensive Model Parameter Control

This release adds extensive parameter control to the Codex CLI provider, enabling fine-grained tuning of reasoning depth, verbosity, and advanced Codex features at both constructor and per-call levels.

✨ New Features

Constructor-Level Parameters

Configure default behavior when creating model instances:

const model = codexCli('gpt-5-codex', {
  allowNpx: true,
  reasoningEffort: 'medium',      // minimal | low | medium | high
  reasoningSummary: 'auto',        // auto | detailed
  modelVerbosity: 'medium',        // low | medium | high
  webSearch: true,                 // Enable web search tool
  includePlanTool: true,           // Enable experimental plan tool
  profile: 'production',           // Load config profile
  configOverrides: {               // Set any Codex CLI config value
    'sandbox_workspace_write.network_access': true
  }
});

Per-Call Parameter Overrides

Dynamically override settings per request using AI SDK v5 standard pattern:

// Simple query - use low effort
await generateText({
  model,
  prompt: 'What is 2+2?',
  providerOptions: {
    'codex-cli': { 
      reasoningEffort: 'low',
      textVerbosity: 'low'
    }
  }
});

// Complex analysis - use high effort
await generateText({
  model,
  prompt: 'Design a distributed system...',
  providerOptions: {
    'codex-cli': { 
      reasoningEffort: 'high',
      reasoningSummary: 'detailed',
      textVerbosity: 'high'
    }
  }
});

New Parameters

Reasoning Control:

• reasoningEffort: Control reasoning depth for o3, o4-mini, gpt-5, gpt-5-codex
• reasoningSummary: Control summary detail level
• reasoningSummaryFormat: Experimental format control

Verbosity Control:

• modelVerbosity: GPT-5 family output length control

Advanced Codex Features:

• includePlanTool: Enable experimental plan tool
• profile: Load config profile from ~/.codex/config.toml
• oss: Use OSS provider
• webSearch: Enable web search tool

Generic Config Overrides:

• configOverrides: Ultimate flexibility - set ANY Codex CLI config value
• Nested objects flatten to dotted keys automatically
• Arrays serialized to JSON strings

Type System Enhancements

New exported types for full TypeScript support:

• ReasoningEffort
• ReasoningSummary
• ReasoningSummaryFormat
• ModelVerbosity
• CodexCliProviderOptions

📚 Documentation

• README.md: Two new sections with comprehensive usage examples
• Configuration Guide: Complete parameter reference with CLI flag mappings
• Examples:
  • advanced-settings.mjs: Constructor-level parameters demo
  • provider-options.mjs: Per-call override patterns demo
• API Quirks: Documented reasoningSummary validation behavior

🧪 Testing

• ✅ 28 tests passing (4 new provider options tests)
• ✅ 72.74% test coverage
• ✅ Runtime validated via Codex CLI session logs
• ✅ All validation checks passing

🔄 Breaking Changes

None - Fully backward compatible with v0.3.0. All new parameters are optional.

📦 Installation

npm install [email protected]

🔗 Links

• NPM Package: https://www.npmjs.com/package/ai-sdk-provider-codex-cli/v/0.4.0
• Documentation: https://github.com/ben-vargas/ai-sdk-provider-codex-cli#readme
• Changelog: https://github.com/ben-vargas/ai-sdk-provider-codex-cli/blob/main/CHANGELOG.md#040---2025-10-06

v0.3.0 - Tool Streaming Support

Tool Streaming Support

This release adds comprehensive tool streaming support to the AI SDK Codex CLI provider, enabling real-time monitoring of Codex CLI's autonomous tool execution through the AI SDK streaming interface.

✨ New Features

Comprehensive Tool Streaming

• Real-time tool monitoring - Observe tool invocations and results as Codex CLI executes them
• Full event stream - tool-input-start, tool-input-delta, tool-input-end, tool-call, tool-result
• Autonomous execution - All tool-call events include providerExecuted: true (Codex executes tools itself)
• All tool types supported - exec, patch, web_search, mcp_tool_call

Usage Tracking

• Turn-level usage tracking via turn.completed events
• Accurate token counts including cached tokens
• Requires Codex CLI >= 0.44.0

New Examples

• streaming-tool-calls.mjs - Basic tool streaming demonstration
• streaming-multiple-tools.mjs - Complex multi-tool workflows with result tracking

🐛 Bug Fixes

• Empty schema handling - No longer adds additionalProperties: false to empty schemas (e.g., from z.any())
• Text event sequence - Proper emission of text-start before text-delta events
• Stream timing race condition - Use setImmediate to ensure buffered stdout processes completely
• Backward compatibility - Support both item.type (0.44.0+) and item.item_type (legacy) formats
• Usage tracking - Fixed double-counting of cached tokens in total
• Error handling - Added isError: true flag for failed command executions

📝 Documentation

• Comprehensive tool streaming guide in examples/README.md
• Updated README.md with tool streaming section and examples
• Documented current limitations (no output-delta streaming yet)
• Updated all 22 examples with detailed descriptions

🔄 Dependencies

• Updated @openai/codex optional dependency from * to ^0.44.0

⚠️ Current Limitations

No real-time output streaming yet - Tool outputs are delivered in the final tool-result event via the aggregatedOutput field, not as incremental deltas during execution. This requires Codex CLI to add output-delta events to its experimental JSON format.

📦 Installation

```bash
npm install [email protected]
```

🚀 Quick Start

```typescript
import { streamText } from 'ai';
import { codexCli } from 'ai-sdk-provider-codex-cli';

const result = await streamText({
model: codexCli('gpt-5-codex'),
prompt: 'List files and count lines in the largest one'
});

for await (const part of result.fullStream) {
if (part.type === 'tool-call') {
console.log('🔧 Tool invoked:', part.toolName);
}
if (part.type === 'tool-result') {
console.log('✅ Tool completed:', part.output);
}
}
```

🔗 Links

• Pull Request: #4
• Full Changelog: https://github.com/ben-vargas/ai-sdk-provider-codex-cli/blob/main/CHANGELOG.md
• Documentation: https://github.com/ben-vargas/ai-sdk-provider-codex-cli#tool-streaming

v0.2.0 - Native JSON Schema Support

This release migrates the provider from prompt-based JSON extraction to native --output-schema support with OpenAI strict mode, delivering significant token savings and reliability improvements.

🚨 Breaking Changes

• Switched to --experimental-json exclusively (removed deprecated --json flag)
  • Requires Codex CLI >= 0.42.0
• Native --output-schema support replaces prompt engineering for JSON generation
• OpenAI strict mode limitations: No optional fields, format/pattern validators stripped
• New event format from experimental JSON output

✨ Key Features

Native Schema Enforcement

• Direct --output-schema flag support with OpenAI strict mode
• JSON structure enforced at API level (more reliable than prompting)
• Automatic schema sanitization for OpenAI compatibility
• Proper supportsStructuredOutputs flag for AI SDK integration

Token Efficiency

• 100-200 fewer tokens per JSON request (zero prompt overhead)
• No more verbose JSON instructions injected into prompts
• Cleaner, more efficient model interactions

Improved Reliability

• API-level JSON validation with OpenAI strict mode
• Better error handling and validation
• Structured experimental-json JSONL event format
• Proper usage tracking from turn.completed events

📦 What's New

Added

• Native JSON Schema enforcement via --output-schema
• Better usage tracking from experimental JSON format
• Support for session.created, turn.completed, and item.completed events
• Automatic cleanup of temp schema files
• JSON schema sanitizer for OpenAI strict mode compatibility
• New examples:
  • generate-object-native-schema.mjs - Native schema capabilities
  • experimental-json-events.mjs - New event format showcase
• Comprehensive migration guide: docs/ai-sdk-v5/migration-0.2.md
• New LIMITATIONS.md documenting OpenAI strict mode constraints

Removed

• Prompt engineering for JSON mode (~70 lines of extraction logic)
• Legacy --json flag support
• extract-json.ts module (no longer needed)
• Backward compatibility with old event format

📚 Documentation

• CHANGELOG.md - Complete v0.2.0 changes
• LIMITATIONS.md - OpenAI strict mode constraints and streaming behavior
• migration-0.2.md - Migration guide with examples

🔄 Migration

See migration-0.2.md for detailed migration instructions and before/after examples.

Key changes for users:

1. Upgrade Codex CLI to >= 0.42.0
2. No code changes required - native schema support is automatic
3. Be aware of OpenAI strict mode limitations (no optional fields)

📈 Benefits

• Simpler: Removed complex JSON extraction logic
• Faster: 100-200 fewer tokens per request
• More Reliable: API-enforced structure vs prompt engineering
• Better Maintainability: Cleaner, more focused codebase

🙏 Thanks

All examples have been updated and tested. Ready for production use!

Full Changelog: v0.1.0...v0.2.0

v0.1.0 – Codex CLI provider for AI SDK v5

ai-sdk-provider-codex-cli v0.1.0

Initial release of the Codex CLI provider for Vercel AI SDK v5.

Highlights

• LanguageModelV2 provider that spawns OpenAI Codex CLI (codex exec --json).
• Works with generateText, streamText, and generateObject (JSON via prompt engineering + extraction).
• Auth via ChatGPT OAuth (codex login, tokens in ~/.codex/auth.json) or OPENAI_API_KEY.
• Safe non-interactive defaults (approvalMode: on-failure, sandboxMode: workspace-write, skipGitRepoCheck: true).
• Resolution order: local @openai/codex → PATH codex → npx -y @openai/codex (when allowNpx: true).
• Zod v3 and v4 compatible; validation normalizes error shapes.
• Robust examples and docs under examples/ and docs/ai-sdk-v5/.
• Tests included (Vitest + v8 coverage).

Install

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

Quick Start

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

const model = codexCli('gpt-5', {
  allowNpx: true,
  skipGitRepoCheck: true,
  approvalMode: 'on-failure',
  sandboxMode: 'workspace-write',
});

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

Streaming Behavior

Codex exec --json suppresses mid-response deltas. The provider emits early response-metadata, then returns the final assistant text as a single text-delta before finish (the text is read via --output-last-message).

Documentation

• Guide: docs/ai-sdk-v5/guide.md
• Configuration: docs/ai-sdk-v5/configuration.md
• Troubleshooting: docs/ai-sdk-v5/troubleshooting.md
• Limitations: docs/ai-sdk-v5/limitations.md
• Examples: examples/

Limitations

• Node runtime only; spawns a local process (no Edge runtime).
• Image inputs are ignored by this provider.
• Token usage isn’t exposed by Codex CLI exec JSON events.
• Some AI SDK knobs (temperature/topP/penalties/stop) are unsupported; the provider warns and ignores them.