Codex CLI Provider

The codex-cli provider integrates Task Master with OpenAI's Codex CLI via the community AI SDK provider ai-sdk-provider-codex-cli. It uses your ChatGPT subscription (OAuth) via codex login, with optional OPENAI_CODEX_API_KEY support.

Why Use Codex CLI?

The primary benefits of using the codex-cli provider include:

Use Latest OpenAI Models: Access to cutting-edge models like GPT-5, GPT-5.1, GPT-5.2, and GPT-5-Codex via ChatGPT subscription
OAuth Authentication: No API key management needed - authenticate once with codex login
Built-in Tool Execution: Native support for command execution, file changes, MCP tools, and web search
Native JSON Schema Support: Structured output generation without post-processing
Approval/Sandbox Modes: Fine-grained control over command execution and filesystem access for safety

Quickstart

Get up and running with Codex CLI in 3 steps:

bash

# 1. Install Codex CLI globally
npm install -g @openai/codex

# 2. Authenticate with your ChatGPT account
codex login

# 3. Configure Task Master to use Codex CLI
task-master models --set-main gpt-5-codex --codex-cli

Requirements

Node.js: >= 20.0.0
Codex CLI: >= 0.42.0 (>= 0.44.0 recommended)
ChatGPT Subscription: Required for OAuth access (Plus, Pro, Business, Edu, or Enterprise)
Task Master: >= 0.27.3 (version with Codex CLI support)

Checking Your Versions

bash

# Check Node.js version
node --version

# Check Codex CLI version
codex --version

# Check Task Master version
task-master --version

Installation

Install Codex CLI

bash

# Install globally via npm
npm install -g @openai/codex

# Verify installation
codex --version

Expected output: v0.44.0 or higher

Install Task Master (if not already installed)

bash

# Install globally
npm install -g task-master-ai

# Or install in your project
npm install --save-dev task-master-ai

Authentication

OAuth Authentication (Primary Method - Recommended)

The Codex CLI provider is designed to use OAuth authentication with your ChatGPT subscription:

bash

# Launch Codex CLI and authenticate
codex login

This will:

Open a browser window for OAuth authentication
Prompt you to log in with your ChatGPT account
Store authentication credentials locally
Allow Task Master to automatically use these credentials

To verify your authentication:

bash

# Open interactive Codex CLI
codex

# Use /about command to see auth status
/about

Optional: API Key Method

While OAuth is the primary and recommended method, you can optionally use an OpenAI API key:

bash

# In your .env file
OPENAI_CODEX_API_KEY=sk-your-openai-api-key-here

Important Notes:

The API key will only be injected when explicitly provided
OAuth authentication is always preferred when available
Using an API key doesn't provide access to subscription-only models like GPT-5-Codex
For full OpenAI API access with non-subscription models, consider using the standard openai provider instead
OPENAI_CODEX_API_KEY is specific to the codex-cli provider to avoid conflicts with the openai provider's OPENAI_API_KEY

Available Models

The Codex CLI provider supports only models available through ChatGPT subscription:

Model ID	Description	Max Input Tokens	Max Output Tokens	Reasoning Efforts
`gpt-5`	Latest GPT-5 model	272K	128K	-
`gpt-5-codex`	GPT-5 optimized for agentic software engineering	272K	128K	-
`gpt-5.1`	GPT-5.1 with optional reasoning	272K	128K	none, low, medium, high
`gpt-5.1-codex-max`	GPT-5.1 Codex Max with enhanced reasoning	272K	128K	none, low, medium, high, xhigh
`gpt-5.2`	Latest flagship model for coding and agentic tasks	272K	128K	none, low, medium, high, xhigh

Note: These models are only available via OAuth subscription through Codex CLI (ChatGPT Plus, Pro, Business, Edu, or Enterprise plans). For other OpenAI models, use the standard openai provider with an API key.

Research Capabilities: All GPT-5 models support web search tools, making them suitable for the research role in addition to main and fallback roles.

Reasoning Effort: The gpt-5.1-codex-max and gpt-5.2 models support the xhigh reasoning effort level, which provides maximum reasoning capability for complex tasks. Configure via reasoningEffort in your codexCli settings.

Configuration

Basic Configuration

Add Codex CLI to your .taskmaster/config.json:

json

{
  "models": {
    "main": {
      "provider": "codex-cli",
      "modelId": "gpt-5-codex",
      "maxTokens": 128000,
      "temperature": 0.2
    },
    "fallback": {
      "provider": "codex-cli",
      "modelId": "gpt-5",
      "maxTokens": 128000,
      "temperature": 0.2
    }
  }
}

Advanced Configuration with Codex CLI Settings

The codexCli section allows you to customize Codex CLI behavior:

json

{
  "models": {
    "main": {
      "provider": "codex-cli",
      "modelId": "gpt-5-codex",
      "maxTokens": 128000,
      "temperature": 0.2
    }
  },
  "codexCli": {
    "allowNpx": true,
    "skipGitRepoCheck": true,
    "approvalMode": "on-failure",
    "sandboxMode": "workspace-write",
    "verbose": false
  }
}

Codex CLI Settings Reference

Core Settings

allowNpx (boolean, default: false)
- Allow fallback to npx @openai/codex if the CLI is not found on PATH
- Useful for CI environments or systems without global npm installations
- Example: "allowNpx": true
skipGitRepoCheck (boolean, default: false)
- Skip git repository safety check before execution
- Recommended for CI environments or non-repository usage
- Example: "skipGitRepoCheck": true

Execution Control

approvalMode (string)
- Controls when to require user approval for command execution
- Options:
  - "untrusted": Require approval for all commands
  - "on-failure": Only require approval after a command fails (default)
  - "on-request": Approve only when explicitly requested
  - "never": Never require approval (use with caution)
- Example: "approvalMode": "on-failure"
sandboxMode (string)
- Controls filesystem access permissions
- Options:
  - "read-only": Read-only access to filesystem
  - "workspace-write": Allow writes to workspace directory (default)
  - "danger-full-access": Full filesystem access (use with extreme caution)
- Example: "sandboxMode": "workspace-write"

Path and Environment

codexPath (string, optional)
- Custom path to Codex CLI executable
- Useful when Codex is installed in a non-standard location
- Example: "codexPath": "/usr/local/bin/codex"
cwd (string, optional)
- Working directory for Codex CLI execution
- Defaults to current working directory
- Example: "cwd": "/path/to/project"
env (object, optional)
- Additional environment variables for Codex CLI
- Example: "env": { "DEBUG": "true" }

Advanced Settings

fullAuto (boolean, optional)
- Fully automatic mode (equivalent to --full-auto flag)
- Bypasses most approvals for fully automated workflows
- Example: "fullAuto": true
dangerouslyBypassApprovalsAndSandbox (boolean, optional)
- Bypass all safety checks including approvals and sandbox
- WARNING: Use with extreme caution - can execute arbitrary code
- Example: "dangerouslyBypassApprovalsAndSandbox": false
color (string, optional)
- Force color handling in Codex CLI output
- Options: "always", "never", "auto"
- Example: "color": "auto"
outputLastMessageFile (string, optional)
- Write last agent message to specified file
- Useful for debugging or logging
- Example: "outputLastMessageFile": "./last-message.txt"
verbose (boolean, optional)
- Enable verbose provider logging
- Helpful for debugging issues
- Example: "verbose": true

Command-Specific Settings

Override settings for specific Task Master commands:

json

{
  "codexCli": {
    "allowNpx": true,
    "approvalMode": "on-failure",
    "commandSpecific": {
      "parse-prd": {
        "approvalMode": "never",
        "verbose": true
      },
      "expand": {
        "sandboxMode": "read-only"
      },
      "add-task": {
        "approvalMode": "untrusted"
      }
    }
  }
}

Usage

Setting Codex CLI Models

bash

# Set Codex CLI for main role
task-master models --set-main gpt-5-codex --codex-cli

# Set Codex CLI for fallback role
task-master models --set-fallback gpt-5 --codex-cli

# Set Codex CLI for research role
task-master models --set-research gpt-5 --codex-cli

# Verify configuration
task-master models

Using Codex CLI with Task Master Commands

Once configured, use Task Master commands as normal:

bash

# Parse a PRD with Codex CLI
task-master parse-prd my-requirements.txt

# Analyze project complexity
task-master analyze-complexity --research

# Expand a task into subtasks
task-master expand --id=1.2

# Add a new task with AI assistance
task-master add-task --prompt="Implement user authentication" --research

The provider will automatically use your OAuth credentials when Codex CLI is configured.

Codebase Features

The Codex CLI provider is codebase-capable, meaning it can analyze and interact with your project files. This enables advanced features like:

Code Analysis: Understanding your project structure and dependencies
Intelligent Suggestions: Context-aware task recommendations
File Operations: Reading and analyzing project files for better task generation
Pattern Recognition: Identifying common patterns and best practices in your codebase

Enabling Codebase Analysis

Codebase analysis is automatically enabled when:

Your provider is set to codex-cli
enableCodebaseAnalysis is true in your global configuration (default)

To verify or configure:

json

{
  "global": {
    "enableCodebaseAnalysis": true
  }
}

Troubleshooting

"codex: command not found" Error

Symptoms: Task Master reports that the Codex CLI is not found.

Solutions:

Install Codex CLI globally:
bash
```
npm install -g @openai/codex
```
Verify installation:
bash
```
codex --version
```

Alternative: Enable npx fallback:

json

{
  "codexCli": {
    "allowNpx": true
  }
}

"Not logged in" Errors

Symptoms: Authentication errors when trying to use Codex CLI.

Solutions:

Authenticate with OAuth:
bash
```
codex login
```
Verify authentication status:
bash
```
codex
# Then use /about command
```

Re-authenticate if needed:

bash

# Logout first
codex
# Use /auth command to change auth method

# Then login again
codex login

"Old version" Warnings

Symptoms: Warnings about Codex CLI version being outdated.

Solutions:

Check current version:
bash
```
codex --version
```
Upgrade to latest version:
bash
```
npm install -g @openai/codex@latest
```
Verify upgrade:
bash
```
codex --version
```
Should show >= 0.44.0

"Model not available" Errors

Symptoms: Error indicating the requested model is not available.

Causes and Solutions:

Using unsupported model:
- Only GPT-5 family models (gpt-5, gpt-5-codex, gpt-5.1, gpt-5.1-codex-max, gpt-5.2) are available via Codex CLI
- For other OpenAI models or gpt-5.2-pro, use the standard openai provider
Subscription not active:
- Verify your ChatGPT subscription is active
- Check subscription status at https://platform.openai.com
Wrong provider selected:
- Verify you're using --codex-cli flag when setting models
- Check .taskmaster/config.json shows "provider": "codex-cli"

API Key Not Being Used

Symptoms: You've set OPENAI_CODEX_API_KEY but it's not being used.

Expected Behavior:

OAuth authentication is always preferred
API key is only injected when explicitly provided
API key doesn't grant access to subscription-only models

Solutions:

Verify OAuth is working:
bash
```
codex
# Check /about for auth status
```
If you want to force API key usage:
- This is not recommended with Codex CLI
- Consider using the standard openai provider instead

Verify .env file is being loaded:

bash

# Check if .env exists in project root
ls -la .env

# Verify OPENAI_CODEX_API_KEY is set
grep OPENAI_CODEX_API_KEY .env

Approval/Sandbox Issues

Symptoms: Commands are blocked or filesystem access is denied.

Solutions:

Adjust approval mode:

json

{
  "codexCli": {
    "approvalMode": "on-request"
  }
}

Adjust sandbox mode:

json

{
  "codexCli": {
    "sandboxMode": "workspace-write"
  }
}

For fully automated workflows (use cautiously):

json

{
  "codexCli": {
    "fullAuto": true
  }
}

Important Notes

OAuth subscription required: No API key needed for basic operation, but requires active ChatGPT subscription
Model selection: GPT-5 family models available via OAuth (gpt-5, gpt-5-codex, gpt-5.1, gpt-5.1-codex-max, gpt-5.2)
Pricing information: Not available for OAuth models (shows as "Unknown" in cost calculations)
No automatic dependency: The @openai/codex package is not added to Task Master's dependencies - install it globally or enable allowNpx
Codebase analysis: Automatically enabled when using codex-cli provider
Safety first: Default settings prioritize safety with approvalMode: "on-failure" and sandboxMode: "workspace-write"

Codex CLI Provider

Codex CLI Provider

Why Use Codex CLI?

Quickstart

Requirements

Checking Your Versions

Installation

Install Codex CLI

Install Task Master (if not already installed)

Authentication

OAuth Authentication (Primary Method - Recommended)

Optional: API Key Method

Available Models

Configuration

Basic Configuration

Advanced Configuration with Codex CLI Settings

Codex CLI Settings Reference

Core Settings

Execution Control

Path and Environment

Advanced Settings

Command-Specific Settings

Usage

Setting Codex CLI Models

Using Codex CLI with Task Master Commands

Codebase Features

Enabling Codebase Analysis

Troubleshooting

"codex: command not found" Error

"Not logged in" Errors

"Old version" Warnings

"Model not available" Errors

API Key Not Being Used

Approval/Sandbox Issues

Important Notes

See Also